home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
17 Bit Software 6: Level 6
/
17 Bit - Level 6 (1998)(Epic Marketing)[!].iso
/
!applications!
/
imagestudiov2.3.0
/
imagestudio000
/
docs
/
imagestudio.txt
< prev
next >
Wrap
Text File
|
1996-09-07
|
224KB
|
7,834 lines
ImageStudio, shareware image processing and conversion package for the
Amiga.
Copyright (C) 1994,1995 Andy Dean, Graham Dean.
Welcome to ImageStudio, shareware image processing and conversion
package for the Amiga.
This document applies to version 2.3.x, written on 2nd October 1995,
Copyright (C) 1994,1995 Andy Dean, Graham Dean.
Introduction
************
This chapter gives a brief introduction into the features offered by
the program.
Copyright and Disclaimer
========================
No guarantee of any kind is given that the programs described in
this document are 100% reliable. You are using this material at your
own risk. The authors *can not* be made responsible for any damage
which is caused by using these programs.
The unregistered package is freeware, but still copyright by Andy
Dean and Graham Dean. This means that you can copy it freely as long as
you don't ask for a more than nominal copying fee.
The registered version of the program and its associated keyfile
*may not* be freely distributed.
The GIF loader/saver module (gif.isio) remains freely-distributable
for both the registered and unregistered versions of the program. No
charge is made for this module.
Permission is granted to include the unregistered package in
Public-Domain collections, especially in the excellent Fred Fish Amiga
Disk Library (including CD ROM versions of it). The distribution file
may be uploaded to Bulletin Board Systems or FTP servers. If you want
to distribute this package you must not remove or alter any of the
supplied files, although the files may be re-compressed using any Amiga
archiver program.
This program (or parts of it) may not be included or used in
commercial programs unless by written permission from the authors.
Installer and Installer project icon (c) Copyright 1991-93
Commodore-Amiga, Inc. All Rights Reserved. Reproduced and distributed
under license from Commodore.
INSTALLER SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE; NO
WARRANTIES ARE MADE. ALL USE IS AT YOUR OWN RISK. NO LIABILITY OR
RESPONSIBILITY IS ASSUMED.
amigaguide.library (c) Copyright 1991-93 Commodore-Amiga, Inc. All
Rights Reserved. Reproduced and distributed under license from
Commodore.
AMIGAGUIDE SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE; NO
WARRANTIES ARE MADE. ALL USE IS AT YOUR OWN RISK. NO LIABILITY OR
RESPONSIBILITY IS ASSUMED.
Jonathan Forbes, the author of LX, has granted permission to include
the unmodified Version 1.03 LX executable by itself (i.e. without
documentation) with any PUBLIC DOMAIN or SHAREWARE package, provided
that a brief credit note is included in the program's documentation
(see Credits).
Machine requirements
====================
ImageStudio requires the following system to run:
* Workbench 2.04 or above.
* Around 1 megabyte of free memory.
* Several megabytes of free hard disk space.
If ImageStudio is run on an AGA machine (A1200 or A4000), it will
use the new display modes and palette routines to improve the quality
of the internal viewer images.
Brief description
=================
ImageStudio is written for the casual graphics user who wishes to
convert or manipulate various graphics formats on a modest Amiga
system. There are several commercial offerings available, however the
casual user is paying a lot of money for many facilities and options
they would probably never use.
Bitmap graphics, by their nature, usually require large amounts of
RAM. One of the main objectives of ImageStudio was to reduce this
burden by utilising virtual memory - most users have more spare hard
disk space than spare RAM.
ImageStudio works with several buffers at any one time (dependant on
how many levels of undo are specified), each of these buffers can hold
either colour-mapped or 24-bit images. For a detailed description of
colour-mapped and 24-bit images, See Image types.
ImageStudio comes with a fully featured ARexx port, which allows the
writing of macro scripts to automate repetative processes and also
allows communication with other ARexx aware programs. Again, ARexx has
the reputation of being "something pretty difficult", so we've
simplified the use of ARexx in ImageStudio by allowing the user to
create, edit and run scripts entirely within ImageStudio - ImageStudio
even provides a blank template as a starting point for each new script.
List of features
================
General:
* Full 24-bit image buffers, with optimizations for colour-mapped
(palette based) images.
* Up to 100 levels of undo / redo.
* User configurable virtual memory.
* Fully featured, easy to use, ARexx interface.
* Fully font sensitive, style guide complient, user interface.
* Fully CyberGraphX compatibility for both the viewers and the
preview window.
* Modular loaders and savers.
* User saveable preferences.
* Operations applicable to the whole image or a selected region.
* Up to 256 greyshade preview window (with optional dither).
* Zoom on preview window.
* Internal / external viewers.
* Loading / saving / manipulating of AGA image formats (e.g. 256
colours, HAM8) on non-AGA machines.
* Max image size of 32000 x 32000 (crops images to 512 x 512 in the
unregistered version).
* Copy / paste to / from the system clipboard.
* Runs on all Workbench 2.04+ Amiga's - utilises AGA chipset if
available.
* Online AmigaGuide help, as well as ASCII, TeX `.dvi' and
PostScript documentation.
* Multi-level help error requesters.
* Public screen.
* Requires no third party libraries or utilities.
Import:
* IFF-ILBM formats (Standard palette based, HAM6, HAM8, extra half
bright, ILBM24)
* BMP
* Datatypes (with Workbench3.0 and above)
* GIF (conforming to GIF87a or GIF89a)
* IFF-DEEP
* JPEG (conforming to JFIF standard)
* PCX
* PNM (PBM, PGM, PPM, ASCII and binary)
* QRT (DKB, POV)
* SGI
* Targa
* TIFF
* VMEM (internal virtual memory format)
Export:
* IFF-ILBM formats (Standard palette based, HAM6, HAM8, extra half
bright, ILBM24)
* BMP
* EPS
* GIF (conforming to GIF87a or GIF89a)
* IFF-DEEP
* JPEG (conforming to JFIF standard)
* PCX
* PNM (PBM, PGM, PPM, ASCII and binary)
* QRT (DKB, POV)
* SGI
* Targa
* TIFF
* VMEM (internal virtual memory format)
Colour Balance:
* All operations are available to the R,G,B components separately.
* Brightness ( upto ±100%)
* Contrast (non to full)
* Gamma ( + and - )
Convolution:
* Many supplied convolution filters.
* User definable convolutions, load and save to disk.
Effects:
* Built in effects: Dynamic range expansion, FlipX, FlipY, RollX,
RollY, Negative, Greyscale, Highlight, Shadow, Random, Pixelize,
Remove isolated pixels.
Scale:
* Crop to selected region.
* Increase / decrease scale by percentage or absolute image size.
* Simple scale or colour averaged.
Colour reduction:
* Increase colour mapped images to 24-bit.
* Decrease number of colours in 24-bit or colour mapped images via
Heckbert median cut algorithm.
* Dithers available for colour reduction: None, Floyd-Steinberg,
Burkes, Stucki, Sierra, Jarvis, Stevenson-Arce.
Palette:
* Edit palette colours and ranges.
* Save current palette.
* Force palette onto current image, dithering if necessary (all dith
ers available).
Shareware version
=================
To encourage users to register, the freely distributable version of
ImageStudio will crop images to 512x512 pixels. All other operations
are available.
For details on how to register, See How to register.
Starting ImageStudio
====================
ImageStudio can be started from either the Workbench or CLI. From
the Workbench it is simply a case of double-clicking on the icon.
ImageStudio supports shift-clicking on a file to start the program with
(see the Workbench manual for more information).
To start ImageStudio from the CLI, simply type:
run ImageStudio [filename]
where `filename' is an optional file to load in at startup. The full
range of tooltypes is supported, and can be appended to the CLI
command. For example:
run ImageStudio "SCREENNAME=Image2" "PREVIEWDITHER=YES" [filename]
would start the program on a public screen named `Image2' with pre
view dithering on. See Tooltypes, for a full list of available
tooltypes.
Upgrading from version 1.x.x
============================
All versions of ImageStudio from version 2.0.0 require a *keyfile*
to work fully.
Users who have registered the ImageStudio package after v2.0.0 will
be provided with a unique keyfile that can be used immediately.
Users who have registered v1.x.x of the ImageStudio package will
have to create their own keyfile using the `Create keyfile' option
under the `Project' menu. See Create_keyfile, for more details.
The idea of the keyfile is that once a keyfile has been created, it
can be placed somewhere where all the programs in the ImageStudio
package can access it. This is typically either the ImageStudio drawer
or the `S:' directory. The user should never need to create another
keyfile, it should work with all future versions of the software; for
this reason, it is suggested that the keyfile is backed up and kept
somewhere safe, as we will be unwilling to give out replacements should
you loose it.
It should also be noted that each keyfile is unique to each user,
and your keyfile should not be given to others. If the number of
registrations should drop due to people abusing the keyfile scheme and
distributing pirate versions of the program, we shall be forced to do
one or more of the following:
1. Stop providing free upgrades. All programs will be individually
stamped and all upgrades must be paid for.
2. Remove online help and provide printed manuals instead. This will
naturally raise the price substantially.
3. Sell the software to a software publisher for commercial
distribution. This is likely to lead to a large price increase.
4. Stop developing ImageStudio and related products.
We see no reason why we should have to resort to any of these
measures, but if you're using a pirated copy of ImageStudio now and you
refuse to register, you *WILL* force this upon us.
If you are using a pirate copy of ImageStudio, so will hundreds of
others. A hundred orders to us is the difference between us writing the
next version of the program, and us abandoning it. It really is your
choice.
Configuring ImageStudio
=======================
In order to benefit from ImageStudio's virtual memory, it is
recommended that the default location used for the storage of the
temporary files is changed. The default location for the storage of
these files is `T:' which is usually in RAM - we want to move this out
onto harddisk.
To do this, select `Prefs' from the `Project' menu and open up the
prefs requester. Change the TEMPDIR preference to the desired location
for the temporary files. See Prefs, for more information on changing
preference variables.
It is suggested that a drawer be made on a harddisk partition with
lots of space to store these files. For example, make a drawer in your
`Work:' partition called `tmp', and change the TEMPDIR preference to
read `Work:tmp'.
Tutorial
********
This chapter introduces ImageStudio by way of a few tutorials
demonstrating commonly performed operations.
Changing the image format
=========================
The simplest use of ImageStudio is just as a file format converter;
See File formats, for details about the supported file formats.
In this example we will change the image format of the
`FW14B_250x250.gif' from GIF to IFF-ILBM.
1. Load the file `FW14B_250x250.gif' from the `Pics' drawer. To do
this, select `Open' from the `Project' menu. When the file
requester opens, select the file and it will load into ImageStudio.
The greyscale preview will show the image.
2. The Infobar at the bottom of the screen shows the current image
size and number of colours, as well as a fuelgauge showing
progress when applicable. The current co-ordinates of the pointer
are also shown when the preview window is active.
3. Open the save requester. To do this, select `Save' from the
`Project' menu. A requester will open, containing (amongst other
things) possible save formats.
4. Select the file format to save. To do this, click on `IFF-ILBM' in
the listview.
5. Change the filename to avoid overwriting the original file. To do
this, type the new filename - `FW14B_250x250.ilbm' into the
`Filename' string gadget.
6. Save out the file by clicking on the `Save' gadget.
The file will now be saved out as a 256 colour IFF-ILBM onto the
disk.
Note:
* All time consuming operations show their progress in the Infobar's
fuelgauge and can be aborted by clicking on the `Abort' gadget.
Changing the number of colours
==============================
Often it is necessary to reduce the number of colours in an image,
either to reduce the file size or produce images compatible with
non-AGA software.
In this example we will reduce the number of colours in the
`FW14B_250x250.gif' image from 256 colours to 16 colours.
1. Load in the `FW14B_250x250.gif' from the `Pics' drawer, if it not
already loaded.
2. Open the colours requester by selecting `Colours...' from the
`Process' menu.
3. The gadgets in the requester will show that the image is a 256 col
our colour-mapped image. Change the number of colours to 16 by
clicking on the cycle gadget or sliding the `No. of colours'
slider.
4. Leave the `Colour choice' and `Dithering' gadgets for now.
5. Click on `OK' to perform the operation.
6. When the operation is complete, view the image with the internal
viewer by selecting `View' from the `View' menu. A 16 colour Lores
image will be displayed.
7. Remove the internal viewer by clicking the right mouse button.
The colour reduced image should contain all the main colours used in
the original image (blue, yellow, red and grey), but should contain
less shades of the colours. To give the impression of more colours,
dithering can be used to mix pixels of the chosen colours. To perform
the last operation with dithering:
1. Undo the colour reduction operation to return to the original 256
colour image. To do this, select `Undo' from the `Edit' menu.
2. Bring up the colours requester as before and select 16 colours.
Also change the `Dithering' gadget from `None' to
`Floyd-Steinberg'.
3. Click on `OK' to perform the operation.
4. View as before.
The image will now perform more gradual changes to colour changes.
Changing the colour balance
===========================
When receiving images from external sources (scanners, frame grab
bers) it is ofter necessary to change to "colour balance" of the image.
Frame grabbers, for example, may have too much `red' in the image.
In this example we shall see the effects on the
`ColourFace_200x250RED.ham6' image of altering the colour balance.
1. Load in the `ColourFace_200x250RED.ham6' image from the `Pics'
drawer. As the file is in HAM6 format, it is turned into 24-bit
internally.
2. View the image with the internal viewer. As the Amiga doesn't have
true 24-bit screenmodes, the internal viewer will approximate the
24-bit image with a HAM preview screen (HAM6 on ECS machines, HAM8
on AGA machines). It should be obvious from the viewer that the
image is too red.
3. Open the balance floating palette if it is not already open. Do
this by selecting `Show balance' from the `Tools' menu.
4. To remove some of the red component, make sure that we are only
dealing with the red component. To do this, make sure that only the
`Red' checkbox at the bottom of the floating palette is checked.
5. Reduce the brightness slider, by say 20%. The graph on the right of
the floating palette will reflect the change (see Show_balance for
more details on the graph).
6. View the image again, this time the image should have lost much of
its unnatural red tint.
Brightness and contrast work in very much the same way as a TV set,
but gamma may need some explanation.
When printing an image out, it is usual for light colours to be
resolved well and dark colours to be reduced to a dark mush. It is
therefore preferable to have some way boost the brightness of the
mid-dark colours whilst still leaving the very light colours light and
the very dark colours dark. Gamma is the operator to perform this
change. By applying a small amount of positive gamma, a much better
balanced image can be produced for printing out.
See Show_balance, for more information on the balance floating
palette.
Applying an effect
==================
ImageStudio has many built in effects for performing commonly used
operations.
This example will remove some noise from a region of
`HappyFace_240x250.bmp', a simulated scanned image.
1. Load in the `HappyFace_240x250.bmp' image from the `Pics' drawer.
2. The image represents what may happen if you hand scan an image into
the computer - lots of "noise".
3. Open the effects floating palette if it is not already open. Do
this by selecting `Show effects' from the `Tools' menu.
4. Select `Remove isolated pixels' in the listview of the floating
palette. If you clicked on the `Apply' button now, the effect
would be applied to the whole image. To compare the image before
and after the effect, we'll only apply the effect to the left hand
side of the image.
5. Open the `Region co-ords' requester by selecting `Region
co-ords...' from the `Edit' menu. To select the left hand side of
the image, set the following values in the gadgets: Min x = 0, Min
y = 0, Width = 120, Height = 250. Make sure that the radio button
on the left of the requester shows that the Width / Height are
being used, not the Max values; click on `Ok'.
6. A region of "crawling ants" will show the selected region.
7. Click on `Apply' of the effects floating palette. The `Remove
isolated pixels' effect will be applied to the selected region.
8. The left of the image will have had a lot of the noise
automatically removed. Clear the selected region by clicking in
the preview window.
Note:
* Not all effects can be applied to regions and whole images. See
Effects, for a comprehensive description of all the available
effects.
See Show_effects, for more information on the ef fects floating
palette.
Applying a convolution
======================
Convolution is a powerful image processing tool, ImageStudio allows
the user to define their own convolution filters.
This example will apply a `Texture' filter to the
`CheetahFace_250x200.ilbm' image.
1. Load in the `CheetahFace_250x200.ilbm' image from the `Pics'
drawer.
2. The `CheetahFace_250x200.ilbm' image is a 32 colour col our-mapped
image and convolution only works in 24-bit (see Show_convolves for
information on how convolves actually work). We therefore need to
turn the image into a 24-bit.
3. Open the colours requester and click on the `16 million colours'
radio button on the left. Click on `OK'. The image in converted
into 24-bit.
4. Open the convolves floating palette if it is not already open. Do
this by selecting `Show convolves' from the `Tools' menu.
5. There should be many convolution filters in the list, click on
`Texture'.
6. Apply the convolution filter to the image by clicking on `Apply' at
the bottom of the floating palette.
7. After the filter has been applied, you could view the result with
the internal viewer in 24-bit, but for a clearer image we'll
convert it back to 32 colours.
8. Open the colours requester, select `No. colours' = 32 and `Dither'
= `None'. Click on `OK'.
9. Now view the 32 colour image with the internal viewer. The image
now has a rough paper(?) texture applied to it.
Note:
* There are many commonly used convolution filters available, it is
up to the user to build a collection suitable filters for their own
use.
See Show_convolves, for more information on the convolves floating
palette.
Scaling the image
=================
In this example we will scale the `CheetahFace_250x200.ilbm' image
from 250 x 200 pixels down to 80 x 40 (icon size).
1. Load in the `CheetahFace_250x200.ilbm' image from the `Pics'
drawer.
2. Open the scale requester by selecting `Scale...' in the `Process'
menu.
3. Set the `Width' = 80 and `Height' = 40. Click on `OK'.
4. The image is re-scaled to that of an icon.
The finish the creation of the icon, we can load it into Commodore's
`IconEdit' program. Both ImageStudio and IconEdit support the
clipboard, so we can copy the image into the clipboard from ImageStudio
and paste it into IconEdit.
1. Copy the image to the clipboard by selected `Copy' in the `Edit'
menu of ImageStudio.
2. Run IconEdit from the `Tools' drawer of your system partition.
3. Select `Paste' from IconEdit's `Edit' menu. The image will be
copied into IconEdit for final editing.
Menu options
************
This chapter describes ImageStudio's menu options in detail.
Selecting a main menu from the list below will give a list of
sub-menu options.
Project
=======
Select the submenu you wish to investigate.
Open
----
Keyboard shortcut - `Amiga - O'
This is how the user loads in an image into the program.
A file requester will appear, through which the user can select a
file to open. Upon selecting a file, ImageStudio will test the file
against its known file formats - loading the file if the image type is
recognised. If the image format is not recognised, an error will be
shown.
In most cases the image will load directly into ImageStudio; however
in the case of HAM6 and HAM8 formats the image is converted into 24-bit
data as it is loaded in, as ImageStudio cannot work directly on HAM
images. For a detailed description of colour-mapped and 24-bit images,
See Image types.
Save
----
Keyboard shortcut - `Amiga - S'
The save requester allows the user to choose the filename for the
saved image as well as the image's format.
To change the filename, either click in the string gadget and edit
the filename directly or click on the `Choose...' gadget to select the
filename with a file requester.
To change the image format of the file to be saved, click in the
listview on the appropriate format. Depending on the format selected,
depends on whether the `Options...' button is available. Some formats
(e.g. IFF-ILBM) have further options available by clicking on the
`Options...' button.
When the user has selected the filename and the image format, the
file can be saved by clicking on `OK' or no action can be performed by
clicking on `Cancel'. If the currently selected filename already
exists, the user will be warned that they are about to overwrite it.
Screen
------
The user may select the current screen's resolution, number of
colours and font.
Screen mode
The screenmode requester allows the user to change the properties
of the current screen. Click on the desired screenmode as well as
the size, number of colours and overscan settings. To bring the
changes into effect, click on `OK' else to perform no action click
on `Cancel'.
Screen font
The screenfont requester allows the user to choose the font to be
used in all the ImageStudio windows and menus. Any Amiga font can
be used, although if a font which is too large to allow some of the
windows to fit on the screen is chosen, the program will default
back to using topaz 8.
Under Workbench2.04, not all gadgets will scale properly with dif
ferent sized fonts. Checkbox gadgets and mutual exclude (radio but
ton) gadgets will remain a constant size, which may cause some
windows to look slightly strange with very large or very small font
sizes.
Prefs
-----
The user may configure the program to their own needs with the prefs
requester. The requester consists of a scrolling list with all the
available preferences, several gadgets that show the current tooltype
value whilst allowing the user to change it, and a couple of checkboxes
for saving the current screenmode and window positions. When the user
is happy with the current values, they may save them as defaults by
clicking `Save', use them for the current session by clicking `Use' or
discard the changes by clicking `Cancel'.
The preferences in the list are separated into string values (e.g.
filenames, ARexx port name etc...), numeric values (e.g. virtual memory
pagesize, number of undo buffers etc...) and boolean, or ON / OFF
values (e.g. Online AmigaGuide help, splash window on startup etc...).
A short description of the preference is shown on the left of the list,
the tooltype (see Tooltypes) name is shown below.
To change a preference value, click on its name in the list. The
current value will be copied to the text or numeric value below; the
exception to this is a boolean preference, see below. The value is
changed by changing the displayed value in the gadget, it will be
stored as this value if another preference is selected or the user
presses `Save' or `Use'. If a string preference is selected that
requires a filename to be chosen, the `Choose...' gadget can be used to
select the desired filename from a file requester.
Boolean preferences are changed by double-clicking on their entries
in the list. The value will toggle between the two states.
If the user wishes to save the current screenmode or window
positions to be the defaults next time the program is started, they may
click on the `Save screenmode' and / or the `Save window positions'
checkboxes.
When changing any of the preferences that require the use of an
external program (e.g. the external text editor), the string must be
formatted to contain a `%s' placed where the filename should be placed.
The default string of
run sys:Tools/Memacs <NIL: >NIL: "%s"
for the `TEXTEDITOR' preference would run Commodore's Micro-emacs
text editor to edit files. It is recommended that the "run" is added at
the start of the string to run the program in the background (i.e.
ImageStudio doesn't have to wait for the text editor to finish) and
that the double-quotes are placed around the `%s' to allow for
filenames containing spaces.
The preferences values may also be read (see ARexx_PREF_GET) and
written (see ARexx_PREF_SET) from ARexx.
About
-----
This brings up a small requester containing information about the
program version number and the user name (only in registered version).
Info
----
This brings up an information requester containing memory and file
usage information.
The `Memory' figures are the amount of RAM used by the buffers, the
`VMem' figures are the amount of disk space used by the virtual memory.
At the bottom of the requester the amount of free RAM and ARexx port
name is shown.
Help
----
Keyboard shortcut - `Amiga - H'
This brings up the main page of the AmigaGuide document.
In order for AmigaGuide help to work, the following must be
satisfied:
1. Commodore's AmigaGuide help has to be installed on your system.
This comes with Workbench3.0+ and can be freely obtained for
earlier versions of Workbench.
2. The preference `HELP' must be `ON' (see Prefs).
3. The *full* filename of the AmigaGuide helpfile must be given in
the `HELPFILE' preference (see Tooltype_HELPFILE).
It is recommended that help be turned off if you are short of memory.
Once help is running, it can either be accessed by selecting the
`Help' submenu in the `Project' menu or by performing a standard "help
menu pick" on a menu item. To do this, highlight the menu item you item
you wish to know more about, but instead of releasing the right mouse
button to select the item, press `Help' on the key board. To clarify,
perform the following steps:
1. Press right mouse button.
2. Highlight menu item you wish to find out help on.
3. Press `Help' on the keyboard.
4. Release right mouse button.
Create keyfile
--------------
This allows registered users with v1.x.x of ImageStudio to create a
keyfile to `unlock' the freely distributable versions of ImageStudio.
A file requester will open asking the user to select their regis
tered version of ImageStudio v1.x.x. If ImageStudio recognises this as
a registered copy, a keyfile with the name given by the `KEYFILE'
preference (see Tooltype_KEYFILE) will created.
If all is successful, when ImageStudio is next started it will be
fully operational.
A plea:
Please do not give your keyfile to anyone else. Each keyfile is
individual to each user, so should your keyfile get into
distribution it can be traced back to you. Don't try altering your
keyfile, it won't work.
Many thanks for your co-operation in this matter.
Iconify
-------
Keyboard shortcut - `Amiga - !'
This reduces the program to a small icon on the Workbench screen. To
reopen the program, simply double-click on the icon. In order to re
duce the amount of memory used by the program when it is iconified,
some of the working memory used by the program is purged; this could
lead to a freeing of several hundred K of memory, depending on the
virtual memory page size and data in internal caches.
Quit
----
This quits the program. If any changes remain unsaved, the user is
warned before the program quits.
Edit
====
Select the submenu you wish to investigate.
Undo
----
Keyboard shortcut - `Amiga - U'
Undos last operation.
The maximum number of undos is set in the preferences requester, See
Prefs.
Redo
----
Keyboard shortcut - `Amiga - R'
Redos last undo.
The maximum number of redos is set in the preferences requester, See
Prefs.
Copy
----
Keyboard shortcut - `Amiga - C'
Copies the current image to the clipboard.
Once the image has been copied to the clipboard it can be used by
any other program that supports the Amiga clipboard.
Paste
-----
Keyboard shortcut - `Amiga - V'
Reads in image from the clipboard.
Flush buffers
-------------
Flushing the buffers will free any memory and diskspace used by undo
/ redo buffers. The user is warned that once the buffers have been
freed, the data cannot be recovered. The current buffer (i.e. the image
in the preview window) is not affected.
Region co-ords
--------------
Keyboard shortcut - `Amiga - D'
Allows the user to select a region by typing the co-ordinates.
The region co-ords requester allow the user to specify the selected
region by either typing in the co-ordinates of the minimum and maximum
corners of the rectangle or the minimum co-ordinates and the
rectangle's width and height. A radio button on the left of the
requester shows whether the maximum co-ords or the width and height are
to be used to select the region.
If there is already a selected region, these values are copied into
the requester when it is opened.
Region clear
------------
Removes any selected region from the preview window.
As well as this menu item, the region can be cleared by simply
clicking in the preview window.
Select all
----------
Keyboard shortcut - `Amiga - A'
Makes the selected region the whole of the displayed image in the
preview window.
Note:
If the user has zoomed in on a region of the image (see Zoom_in),
`Select all' will not select the whole image but just the displayed
image in the preview window.
View
====
Select the submenu you wish to investigate.
Full image
----------
Keyboard shortcut - `Amiga - F'
Displays the whole image in the preview window.
Zoom in
-------
Keyboard shortcut - `Amiga - <'
Zooms in to make the currently selected region fill the preview
window.
Zoom out
--------
Keyboard shortcut - `Amiga - >'
Zooms out by a factor of 3 times.
Internal viewer
---------------
Keyboard shortcut - `Amiga - I'
Views the current image with the internal viewer.
The user may choose the viewer module to be used via the
INTERNALVIEWER preference (see Tooltype_INTERNALVIEWER) to adapt the
view er's capablities based on the Amiga on which it is being used.
In general, if the image is colour-mapped, the viewer will try and
open a screen with the same number of colours as the image. Viewing
24-bit images is done by using the HAM screenmodes (HAM6 under ECS,
HAM8 under AGA) to approximate the 24-bit image. In order to keep the
viewer reasonably fast, the HAM image sometimes suffers from `colour
fringing' as the approximation is relatively crude (especially under
ECS).
If the CyberGraphX retargetable system is being run on the Amiga
with a compatible graphics card, the image can be viewed using any of
the supplied viewers directly on a 15/16 or 24bit screen.
If the image originated as an IFF-ILBM, the viewer screen will try
and open up in the same screen mode as the image. If this is not
possible, the user may change to a more suitable screenmode with the
`View screenmode' menu option, See View_screenmode.
If the internal viewer won't display the current image, check the
following:
1. If the image was loaded in as an IFF-ILBM, the saved screenmode may
not be supported by your machine. For example, the screenmode may
be `Productivity' and your machine doesn't have a multiscan
monitor. Simply change the screenmode to one your machine does
support - e.g. `Hires Laced'
2. A colour-mapped image contains more colours than it is possible to
show on a ECS machine. Either reduce the number of colours in the
image to a number that can be displayed or use the `amigaplus.isio'
internal viewer to display an approximation in a HAM screen.
3. Make sure you have enough CHIP RAM free to open the screen. Large
256 colour and 16 million colours images take lots of CHIP RAM.
To stop the viewer at any time, press the right mouse button or
click on `Abort' in the infobar.
The following internal viewer modules causes slight differences in
the behaviour in the way the image is handled in certain cases:
amiga.isio
This module will work with both ECS and AGA Amigas. Colour-mapped
images are displayed directly (upto 16 or 32 colours on ECS
machines, 256 colours on AGA Amigas) and 24 bit images are shown on
HAM6 screens. If the viewer cannot open the desired colour mapped
screen, it fails.
amiga-aga.isio
This module will only work with AGA Amigas. It functions exactly
the same as the `amiga.isio' module, only it displays 24 bit
images in HAM8.
amigaplus.isio
This module is aimed at the ECS Amiga, essentially being the
`amiga.isio' module but with the automatic capability of being able
to display colour mapped images as HAM6 if the colour mapped image
has too many image for the ECS chipset to display directly. This is
useful for viewing the many 256 colour images on an ECS Amiga.
View screenmode
---------------
This allows the user to set the screenmode of the image, and there
fore of the internal viewer.
Click on the desired screenmode for the image in the screenmode
requester. The current screenmode is highlighted in the listview.
External viewer
---------------
Uses an external viewer program to view the image.
This calls up the external viewer program to view the current image.
If a third party 24-bit graphics card is installed, a viewer can be
used to view the image on that.
To specify the external viewer to use, See Prefs.
Process
=======
Select the submenu you wish to investigate.
Crop
----
Keyboard shortcut - `Amiga - W'
Crops the current image to the selected region.
This reduces the image to only that which is in the selected region.
A region must be selected in order for this operation to work.
Scale
-----
Keyboard shortcut - `Amiga - L'
Reduces / increases the size of the image.
The scale requester allows the user to change the image's width /
height by either selecting the absolute size of the new image or the
percentage by which to scale. A radio gadget to the left shows which
operation will be performed.
The percentage value may also be changed by sliding the width and
height sliders to achieve the desired final size; divide and multiply
by 2 buttons are provided to quickly scale the image by common amounts.
Finally, two methods of scaling are supported: fast and colour
average. Fast scaling works with both colour-mapped and 24-bit images
and produces results adequate for most needs. If the image is to be
scaled up by a large amount the image may become very `blocky' and if
the image is scaled down a large amount, information in the image may
be lost. To reduce this, colour average scaling is available on 24-bit
images which reduces blockiness when increasing the scale and reduces
information loss when reducing the scale. Colour average rescale can
take significantly longer than a fast rescale.
Colours
-------
Keyboard shortcut - `Amiga - K'
Allows increasing / decreasing of the number of colours in the im
age, with various dithers.
The colours requester allows the user control over the number of
colours in the image. A radio button on the left hand side shows
whether the current image is colour-mapped or 24-bit.
To increase the number of colours in a colour-mapped image, simply
select the new number of colours with the top cycle gadget or the `No.
colours' slider. Although the number of colours need not be a power of
2 (2, 4, 8, 16, 32, 64, 128 or 256), internally the number will be
rounded up to the nearest power of 2. If, for example, a 16 colour
picture was increased to 20 colours then the image would be come a 32
colour image.
Colour-mapped images can also be turned into 24-bit images by click
ing on the `16 million colours' radio button on the left hand side of
the requester. This is useful if the user wishes to perform an
operation on a colour-mapped image that can only be performed on a
24-bit image. The resultant 24-bit image can then be turned back into a
colour-mapped image after the operation is complete.
To reduce the number of colours in an image, the same process is
followed as above with a few differences. Whereas increasing the number
of colours in an image does not lose any image information, it is
enevitable that reducing the number of colours must lose some of the
colour information. In order to help reduce the effect of this, two
other aids are used: dithering and palette choice.
The result of colour reduction is always a colour-mapped image. The
user may select the number of colours in the final image with the top
cycle gadget or the `No. colours' slider. Again, although the number of
colours need not be a power of 2 (2, 4, 8, 16, 32, 64, 128 or 256),
internally the number will be rounded up to the nearest power of 2.
This though can be useful, as the user may want to re duce a 24-bit
image down to 30 colours - leaving 2 spare for his / her own use.
In order to give the impression of more colours in the reduced col
our image, dithering can be employed to smoothly distribute colours
over areas of high colour change. `Floyd-Steinberg' is the most common
method and works well in most cases. For larger images, better contrast
can be obtained by using a more computationally intensive dither
(`Burkes', `Stucki', `Sierra', `Jarvis') and for the user with large
images and lots of time to spare, `Stevenson-Arce'. Again, there is no
hard and fast rule which method of dithering is best; if you're not
happy with the result, try a different method.
Palette
-------
Allows the saving of the current palette and loading of new palette
onto the current image.
Palettes can either be loaded, saved and edited in ImageStudio:
Palette load
This is used to force a palette onto an image. The requester allows
the user to choose the palette to load and any dithering to be
applied to the image, See Colours. Various sample palettes are
given with the distribution to map the image to the Workbench
colours or a general purpose palette. New palettes can be generated
with any popular paint package(1).
Palette save
Saves the current palette out to the filename chosen by the user in
the requester. The palette file is compatible with the popular
paint packages. This option has no relevance for 24-bit images, as
they have no palette.
Palette edit
This brings up the palette edit requester. Here the user may edit
each colour individually or move the colours around with the `Copy'
and `Swap' operations. Colour ranges can be created and ranges may
be sorted into order of increasing or decreasing luminosity.
To edit a colour, simply click on the colour in the scrolling
viewer and edit the R,G,B or H,S,V colour values (see Colour
representations).
To copy or swap two colours, click on the first one in the
scrolling viewer then click on either `Copy' or `Swap'. The
pointer will change to a "To" pointer to allow you to click on
another colour to swap or copy to.
To create a colour spread, alter one colour to be the start of the
spread and alter another colour to be the end of the spread. Click
ing on the first colour, then on `Spread', the on the end colour
will cause a smooth transition of colours between the start and end
colours.
Sorting the colours is like a colour spread, only no colour values
are actually changed. Simply click on the start of the sort,
followed by either of the `Sort' buttons and finally on the end
colour. The colours between these values will be sorted into
either an in creasing or decreasing order of luminosity.
Finally, to apply the new colour palette to the image click on
`OK'. To remap the image to the new palette (swap the old colours
with their nearest match in the new palette), click on `Remap'.
Whilst changing the colours in the scrolling viewer, the colours in
the preview window will change. *This is not a representation of
what is happening to the image!*.
---------- Footnotes ----------
(1) Except Brilliance, which seems to save all 384 colours of its
palette.
Tools
=====
Select the submenu you wish to investigate.
Command shell
-------------
Keyboard shortcut - `Amiga - 0'
Opens the ARexx command shell.
The command shell allows the user to enter ARexx commands directly,
without having to write a script file (see Show_scripts). This means
that the effect of the ARexx command may be seen directly, allowing the
commands to be experimented with before adding them to a script.
The values returned by a command are displayed in a readable form in
the command shell.
It should be noted that the command shell differs from executing an
actual ARexx script in the following ways:
1. Each entered command is passed directly to ImageStudio without
going through ARexx first. This means that no ARexx statements can
be used (e.g. loops) and no variables may be defined.
2. The string entered in the command shell is *exactly* what is seen
by the ImageStudio command parser - nothing is evaluated. It is
not neccessary therefore to enclose strings in both single and
double quotes to stop them from being evaluated. For example, the
following line is valid in the command shell, but invalid in an
ARexx script as the string would have its quotes removed (see
Common ARexx problems):
REQUEST_MESSAGE TEXT "A string with spaces in it"
Help on a particular command's template (see Command templates) can
be obtained by typing:
help <command>
in the command shell. The command's template for the input and
return values will be show.
Show balance
------------
Keyboard shortcut - `Amiga - 1'
Opens / closes the balance floating palette.
The balance floating palette is used to control the brightness,
contrast and gamma of the current image. On 24-bit images, the colour
balance can be altered on selected regions as well as the whole image
whereas colour-mapped images only allow alterations to the whole image.
The colour balance effects are usually applied to all the red /
green / blue components simultaneously, but each component can be
altered individually by checking the `Red', `Green' or `Blue' check
boxes at the bottom of the floating palette.
The effect of changing either the brightness, contrast or gamma can
be seen in the graph on the right hand side of the floating palette.
The graph shows the input RGB component along the X-axis and the output
RGB component along the Y-axis.
output
Light RGB ^
|
|
|
|
|
Dark RGB |
+-------> input
Dark RGB Light RGB
No operation is shown therefore with a straight diagonal line - the
input value is mapped to the same output value.
output
^
| /
x|____/
| /|
| / |
| / |
|/ |
+-------> input
x
Brightness
Altering the brightness is achieved by mutliplying up / down the
RGB components by the specified amount. The range of the slider is
from -100% (everything becomes black) to +100% (everything is
twice as bright).
Contrast
Altering the contrast forces dark colours darker and light colours
lighter. The range of the slider is from -100% (everything becomes
mid grey) to +100% (RGB components are either on/off).
Note: 100% contrast on a colour image doesn't produce a black and
white image as may be expected. As each RGB component is treated
individually, it leaves you with an 8 colour image - the 8 colours
being composed of combinations of the RGB components as below:
Black
0% Red, 0% Green, 0% Blue
Red
100% Red, 0% Green, 0% Blue
Green
0% Red, 100% Green, 0% Blue
Blue
0% Red, 0% Green, 100% Blue
Yellow
100% Red, 100% Green, 0% Blue
Magenta
100% Red, 0% Green, 100% Blue
Cyan
0% Red, 100% Green, 100% Blue
White
100% Red, 100% Green, 100% Blue
If you wish to turn a colour image into 2 colour black and white,
greyscale the image first with the greyscale effect, See Effects.
Gamma
Adjusting the gamma of an image has the effect of lightening some
of the mid-dark colours, whilst leaving the dark colours dark.
This can often enhance the eye's perception of the image, as the
eye is more responsive to light colours. Gamma correction can also
be useful when printing an image out, as mid-dark colours tend to
get printed too dark.
Only small alterations are usually needed with this operator (-20%
to +20%).
Show effects
------------
Keyboard shortcut - `Amiga - 2'
Opens / closes the effects floating palette.
The effects floating palette contains a list of ImageStudio's built
in effects. Not all types of effect can be applied to all types of
buffer, the details are given below. Any numerical values required by
the individual effects are set using the slider on the effect floating
palette.
An effect can be applied by clicking on the `Apply' button or
double-clicking on the list entry.
See Effects, for details of all available effects.
Show convolves
--------------
Keyboard shortcut - `Amiga - 3'
Opens / closes the convolves floating palette.
The convolves floating palette allows the user to apply their own
convolution effects to a 24-bit image; convolution will not work on
colour-mapped images.
To create a new convolution filter, select `New' and then `Edit'
from the floating palette. The convolve grid requester contains the
convolution filter's name at the top as well as gadgets for the filter,
divisor and bias values. When the user has set the filter values, click
on `OK' to return to the convolve floating palette.
To apply a filter, select it in the listview and click on `Apply'.
To delete a filter from the list, click on `Del'. This will not delete
the file from the disk, this has to be done from the Workbench.
To scan a new drawer for convolution filters, click on `Load' and
select a directory to scan. To save the current list's convolution
filters, click on `Save' and select a drawer to save to.
The default drawer to scan at startup is set in the preferences, See
Prefs.
A convolve can be applied by clicking on the `Apply' button or
double-clicking on the list entry.
What follows is a quick description of convolution, it is not
necessary to understand this to use the filters.
It is convenient think of the convolution filter as an array of
numbers that "slides" over the image a pixel at a time. To find the new
colour value of the pixel at the centre of the filter, multiply the
filter values by the values of the colours under the array then divide
the result by the `Div' value, then add the `Bias' value.
If we take the example of 3 x 3 `blur low' filter being applied to
the pixels below:
filter pixels
0 1 0 a b c
1 2 1 convolved with d e f gives:
0 1 0 g h i
((0 x a) + (1 x b) + (0 x c) + (1 x d) + (2 x e) + (1 x f) + (0 x g)
+ (1 x h) + (0 x i)) / Div + Bias
which would be applied to the new pixel in the position of the `e'
pixel.
Although the pixels shown above are shown as `a', `b' etc... they
are actually the 3 red, green and blue values that comprise the colour.
Examples:
1. 0 0 0
0 1 0
0 0 0
Div = 3, Bias = 0
would make each pixel one third of its original brightness.
2. 0 0 0
0 0 0
0 1 0
Div = 1, Bias = 0
would move each pixel up by one.
3. 0 0 0
0 1 0
0 0 0
Div = 1, Bias = 50
would add 50 onto each of the red, green, blue components of the
centre pixel.
Note:
* The red, green, blue components of a pixel can have values in the
range 0 to 255. If a convolution value is greater than 255 it is
made equal to 255. Similarly if a convolution value is less than 0
it is made equal to 0.
* ImageStudio has optimized routines for 1x1, 3x3 and 5x5 filters. If
the program detects that only values in a 3x3 filter are being
used, only calculations for a 3x3 filter are performed.
Show scripts
------------
Keyboard shortcut - `Amiga - 4'
Opens / closes the scripts floating palette.
The scripts floating palette gives a list of easily available ARexx
scripts for the user to apply.
To execute a script in the list, select the desired script and click
on `Apply' or simply double-click on the list entry. The script can be
stopped by either clicking on `Abort' during any operation or choosing
`Cancel' on any given requester (if the script is written correctly,
that is). See Writing scripts, for more information on creating ARexx
scripts.
New scripts can be created by clicking on `New...' button. The user
is requested to name the new script and it is placed in the listview.
By default, the script will already contain some ARexx commands to help
the user - the user simply adds what is neccessary.
To edit the currently selected script, the `Edit...' button is used.
The text editor set in the preferences (see Prefs) is used to edit the
file.
The `Load...' button allows the user to scan another directory for
ARexx script files. `Other...' will let the user select another ARexx
script file to run, without adding it to the list.
Show coords
-----------
Keyboard shortcut - `Amiga - 5'
Opens / closes co-ords floating palette.
The co-ords floating palette shows the current position in the image
of the mouse pointer. When dragging box to select a region, the current
region width and height are shown.
ARexx
*****
This chapter gives information about the program's interface to the
ARexx programming language.
Introduction to ARexx
=====================
ARexx is the script language that is distributed with all Amigas
sporting Workbench 2.04 and above. It is used on the Amiga for two main
tasks:
1. Providing an easy and consistent method of adding macro facilities
to programs.
2. To allow ARexx aware programs to communicate with each other.
Most users are dissuaded from using ARexx with their programs be
cause of the learning curve involved in (i) learning ARexx and (ii)
using the functions provided with each program. With ImageStudio, we
have tried to simplify the process of creating an ARexx script by:
1. Providing an easy interface for creating and running the scripts.
2. Providing a ready-made script template which the user can just
"fill in the blanks" to produce a fully working program.
3. Providing many commands to perform commonly performed operations.
This means the user needs to write less code in ARexx and doesn't
need to rely on external utilities and libraries to perform the
operations.
Typical uses for ARexx in ImageStudio include:
* Batch processing. ImageStudio can now be told to repeatedly perform
the same operation on many images. The user could, for example,
convert all PCX files in a given directory into IFF-ILBM files.
* Background processing. ImageStudio can be told to watch a given di
rectory and whenever a new file is generated to perform a set of op
erations on it. This is useful for producing ray-traced animations,
where each frame of the animation could be converted from 24bits to
HAM6 (say) as each frame was generated by the ray tracer.
* Adding additional image manipulation abilities to other programs.
ImageStudio could be passed an image from another program, process
it, then return it back to the original program. By using a desktop
publishing package that supports ARexx, an image could be saved
from the DTP program, gamma corrected by ImageStudio, then
reloaded back into the DTP program all automatically.
Many example files are given with ImageStudio (see Example scripts),
which can either be used directly or modified to perform the desired
operation.
In order for ARexx to be available to ImageStudio, you must start
ARexx at startup time by including the line:
rexxmast >NIL:
in your `User-Startup' file in the `S:' directory. Normally this
line should be present in your User-Startup, but if you find no scripts
run from ImageStudio you must add this line manually.
Writing scripts
===============
We have tried to simplify the process of writing an ARexx script as
much a possible to provide access to the power of ARexx scripts without
(too much(!)) pain.
An ARexx script can be written and run without ever having to leave
ImageStudio. The only extra tool needed is a text editor; ImageStudio
can be configured to use your favourite text editor by changing the
program's preferences (see Prefs). The basic process of creating an
ARexx script is as follows:
1. Open the `Scripts' floating palette.
2. Create and name the new script by clicking on `New...'.
3. Load the blank script template into your editor by clicking on
`Edit...'.
4. Add the desired commands to the template in the space provided.
5. Save the file and exit the text editor.
6. Run the script by clicking on the `Apply' button on the scripts
floating palette.
Any errors the script may generate will be displayed in a requester
on the ImageStudio screen.
To try this process out, try the following:
1. Open the `Scripts' floating palette.
2. Click on `New...' and call the script "FirstScript".
3. Edit the new script by clicking on `Edit...'.
4. In the space provided in the script, type the following lines:
OPEN "Pics/FW14B_250x250.gif"
SCALE 80 40
PALETTE_LOAD "Palettes/Workbench4.palette" DITHER FS
VIEW
5. Save the file and exit the text editor.
6. Run the script by clicking on the `Apply' button on the scripts
floating palette.
The result of the above script should be a 4 colour icon sized image
of a Formula1 racing car. This could now be copied into the clip board
by selecting `Copy' in the `Edit' menu and pasted into Commodore's
IconEdit program for final conversion into an icon. Alternatively, the
command to copy the image into the clipboard could be added to the end
of the script.
See ARexx commands, for a full description of the ARexx commands
used in the above example.
Note, please don't remove the "/* BEGIN PROGRAM ****" and corre
sponding "END PROGRAM" lines in the blank macro template - these will
be used to insert the recorded ARexx macros when they are implemented
(see Future additions).
Basic ARexx
===========
This section is meant as a beginners guide to using ARexx with Imag
eStudio. We cannot hope to teach you the ARexx language, although it is
only neccessary to the know the very basics to start using ARexx
scripts with ImageStudio. It is assumed that the user is editing and
running their scripts from within ImageStudio (see Show_scripts).
For further information on ARexx, we suggest reading Commodore's
ARexx user guide supplied with the A4000 or the Workbench2 and 3 up
grade packs. For A600 and A1200 users who don't get this manual, we
recommend the "ARexxGuide" AmigaGuide document by Robin Evans which is
a shareware document containing extensive information on the ARexx
language. The guide can be obtained from all good PD houses.
The ARexx programming language is similar to many other programming
languages in its structure. Users who have BASIC, C, FORTRAN, Pascal,
Modula2 or Oberon experience will notice many similarites. It is not
similar to Assember language, Lisp or Prolog. An ARexx pro gram is, in
its simplest form, a list of instructions for ImageStudio to perform.
Here is a simple ARexx program:
/* A simple ARexx program */
REQUEST_MESSAGE TEXT '"Hello world!"'
exit
This shows some important things about an ARexx program:
1. All ARexx programs *must* start with a comment line. A comment
line is a line which starts with the `/*' sequence of characters
and ends with the `*/' characters. Anything between these
characters is ignored by ARexx.
2. For clarity, all of ImageStudio's commands are shown CAPITALISED,
ARexx commands are kept in lower case. REQUEST_MESSAGE is therefore
an ImageStudio command that should be performed.
3. The REQUEST_MESSAGE has some `arguments' or `parameters' following
it. These tell the REQUEST_MESSAGE command how to behave, in this
case they tell the command to pop up greeting message.
4. To stop an ARexx program, use the command `exit'.
OK, lets enhance our program a little:
/* A better simple ARexx program */
REQUEST_MESSAGE TEXT '"What do you think of\n'||,
'the show so far?"',
BUTTONTEXT "Great|Mediocre|Rubbish"
exit
From this example we learn:
1. To separate a long command line, place a comma `,' as the last
character on the line. This tells ARexx to treat the next line as a
continuation of the previous. Two line breaks are used in the above
example.
2. ARexx loves to evaluate things. If we want to stop ARexx evaluating
variables, the variable should be enclosed in single quotes ` ' '.
See ARexx problem 1, if little explanation is needed as to the many
double and single quotes used above. If we now tell you that the `\n'
characters are used represent a newline and the `||' characters glue
string together, we should see that:
'"What do you think of\n'||'the show so far?"'
would be evaluated to:
"What do you think of*the show so far?"
where `*' represents a newline. The lesson to be learnt here is that
whenever you use a string (with or without spaces) it is best to
enclose the whole thing in single quotes outside the double quotes to
keep the whole thing together.
On with the examples. The previous script isn't much use if we can't
test for which button the user pressed, so:
/* A better simple ARexx program */
options results
REQUEST_MESSAGE TEXT '"What do you think of\n'||,
'the show so far?"',
BUTTONTEXT "Great|Mediocre|Rubbish"
if RESULT == 0 then
REQUEST_MESSAGE TEXT '"Sorry, I was trying very hard."'
else if RESULT == 2 then
REQUEST_MESSAGE TEXT '"It gets better."'
else do
REQUEST_MESSAGE TEXT '"We like happy users."'
REQUEST_MESSAGE TEXT '"Treat yourself to a coffee."'
end
exit
This shows:
1. Normally ARexx ignores the values returned by commands. To allow
commands to return values, use "options results"; this is done for
you in the blank ARexx script.
2. Unless otherwise specified (see Return values) commands return the
results of their operation in a variable called "RESULT". The
command REQUEST_MESSAGE returns the value of the button that the
user pressed. It is this value that we can test for.
3. The `if' tests are shown above. Note that if you only want to
perform one operation as part of the `if', you can just place it
after the `then'. If you wish to perform more operations, they
must be placed in a `do / end' set.
OK, that's about it for the introduction to ARexx. We really suggest
now that you look at the example scripts provided with ImageStudio (see
Example scripts) to learn more examples. Have fun!
Note, if you use any ARexx command which prints text out (e.g.
"say"), this text is printed to the file given by the tooltype
REXXOUTPUT (see Tooltype_REXXOUTPUT). After the script has been
executed, this file can be examined.
Command templates
=================
The parameters passed to the ARexx commands closely follow
Commodore's style guidelines. The parsing of the arguments follows the
standard template format described below.
Commands are always of the form:
command [options]
The command may be something like `OPEN' or `SCALE' and the options
may be filenames, numbers etc... A typical command template may look
like:
OPEN FILE/A,FORMAT,ARGS,FORCE/S
The commands and options are not case sensitive, therefore `OPEN',
`Open' or `open' can be used to open a file. The options after the
command name are separated by commas, and are named (e.g. FILE or FORCE
are option names). After the name, follows an optional modi fier (e.g.
/A or /S are modifiers) which describes what type of in formation the
option specifies.
When using the command, the option names may be ommitted if the
parameters for the command are given in the same order as the options
in the template, but for clarity it is recommended that the option
names be used.
The following modifiers are used:
No modifier
If the option has no modifier, the option is expecting a string.
Strings are lines of text with no spaces; to use a string with a
space, place the string in double-quotes (").
Multiple strings (/M)
Many strings can be specified if an option uses this modifier.
Numeric (/N)
Numeric options allow both positive and negative integers. Floating
point numbers are not yet used by ImageStudio.
Boolean (/S)
Some options can be specified to "switch" that option on. By
leaving the option out, the option is switched off.
Keyword (/K)
A keyword option shows that the option name must be used to set
this option.
Always (/A)
This option must always be included in this command.
In practice, it soon becomes very easy to interpret command
templates - some examples with explanations are given below:
OPEN FILE/A,FORMAT,ARGS,FORCE/S
The command `OPEN' is used to open a file and load it into
ImageStudio. OPEN requires a filename (FILE/A is a string, and is
always required), an optional FORMAT string, an optional ARGS string
and and optional FORCE switch. The following are valid OPEN commands:
The following would load a file called
`Pics/CheetahFace250x200.ilbm', forcing the old project to be over
written:
OPEN FILE "Pics/CheetahFace250x200.ilbm" FORCE
The following would load a file called `Ram Disk:Tulip.jpg', asking
first if the current project has changed:
OPEN '"Ram Disk:Tulip.jpg"'
The following is an error, if the filename has spaces in it, it
should be enclosed in single and double-quotes:
OPEN "Ram Disk:Tulip.jpg"
SCALE X/N,Y/N,PERCENT/S,METHOD
`SCALE' is used to change the size of the image (see ARexx_SCALE).
SCALE expects two numerical values (X/N,Y/N are numbers but neither are
required), can be used to scale either to an absolute size or by a
given percentage (adding the PER CENT switch specifies percentage
scaling) and can use a variety of methods (METHOD is used to specify a
description string of the method to be used - again, if this is not
specified a default method is used). The following are valid SCALE
commands:
The following scales the image to 640x480 pixels:
SCALE X 640 Y 480
The following makes the image 50 percent of its original height:
SCALE Y 50 PERCENT
The following scales the image to 800x600 pixels using the colour
averaging method:
SCALE 800 600 METHOD AVERAGE
The following is an error, no X or Y values given:
SCALE X PERCENT
The following is an error, floating point values are not allowed:
SCALE Y 127.5
See ARexx commands, for more detailed descriptions of each of the
individual ARexx commands.
Return values
=============
The return values for the ARexx commands are specified in the same
notation as the input parameters, although the types of returned values
is more limited than the input parameter types. In order for results to
be returned from ARexx commands, it is essential that the line:
options results
be placed near the start of the ARexx script.
Commands may return either strings, numbers or arrays of either. By
default, all ARexx commands return their values in a variable called
"RESULT". This is fine if the command returns a single number or
string. For example, the following call to the FILE_JOIN command (see
ARexx_FILE_JOIN) would return the string "T:Image.ilbm" in the RESULT
variable:
FILE_JOIN PATHPART "T:" FILEPART "Image.ilbm"
If the user wishes to return the result in another variable other
than RESULT, they may specify the VAR keyword. For example, the
following would perform the same action as above, only putting the
result in the varible called "FULLNAME"
FILE_JOIN PATHPART "T:" FILEPART "Image.ilbm" VAR FULLNAME
Some ARexx commands return multiple values, and these to can be re
turned in a single variable - each returned value in the variable is
seperated with a space. The following returns information about the
current image (see ARexx_IMAGEINFO_GET):
IMAGEINFO_GET
and the RESULT variable might look something like:
640 400 8 Pics/Zebra.ilbm 32772
It is possible then to extract the desired information using ARexx's
built in parsing routines. A neater way to return multiple values
though is through a "stem" variable. Here, a base name for a variable
is given and the returned values' names get added to it. It is clearer
with an example:
IMAGEINFO_GET STEM IMAGEINFO.
would return the same information as previously, only it would
create the following variables:
IMAGEINFO.WIDTH = 640
IMAGEINFO.HEIGHT = 400
IMAGEINFO.DEPTH = 8
IMAGEINFO.FILE = Pics/Zebra.ilbm
IMAGEINFO.MODEID = 32772
Now you can refer easily to the returned values.
If an ARexx function returns an array of results, they are named as
follows:
STEMNAME.RESULTNAME.NUMBER
with the variable STEMNAME.RESULTNAME.COUNT holding the number of
returned results. Again, an example being the following which gets all
the ".ilbm" images in the "Pics" dirctory:
FILES_MATCH PATHPART "Pics" PATTERN "#?.ilbm" STEM MATCHED.
which might return the following:
MATCHED.FILEPARTS.COUNT = 4
MATCHED.FILEPARTS.0 = Zebra.ilbm
MATCHED.FILEPARTS.1 = WilliamsFW14B.ilbm
MATCHED.FILEPARTS.2 = Spitfire.ilbm
MATCHED.FILEPARTS.3 = Brightside.ilbm
See ARexx tips, for more information on how to turn array stem
variables into string variables.
Error checking
==============
ImageStudio uses the standard ARexx method of returning errors, with
a further extension.
Whenever a command is executed, a variable called "RC" has its value
set by ARexx. If the command executed normally, RC is set to zero. If
any failure happened, RC is set to either 5 (warning), 10 (failure) or
20 (serious failure).
ImageStudio also sets the value of a further variable called "RC2",
which either contains a text description of the reason for failure or a
standard AmigaDos error code.
A description string is returned in RC2 if a failure occurs within
the execution of a command. RC2 will be an AmigaDos error number if
there is an error with the command syntax (e.g. mis-spelled command
name or missing quotes).
If, for example the user was to try to use the scale command when
there was no image in the buffer, RC and RC2 would be set to the
following:
RC = 10
RC2 = "SCALE, No image"
If the scale operation were to be performed with the command:
SCLAE 80 40
the following values would be set:
RC = 10
RC2 = 236
where AmigaDos error 236 represents `not implemented', i.e. unknown
command. The default blank script template will convert the most common
likely AmigaDos error codes into description strings (see Commodore's
AmigaDos manual for a full description of AmigaDos errors).
By default, the blank script template turns on automatic error
checking. The line:
signal on error
tells ImageStudio to jump to the ERROR: label whenever a command
fails. The blank script then puts up a requester showing the error.
The user may wish to turn off the automatic error checking to
perform error checking themselves. This is neccessary, for example, if
the user wishes to trap the user pressing `Cancel' on a requester (this
returns an error). The following checks when the user cancels the file
requester:
/* Turn off automatic error checking */
signal off error
/* Open the requester */
REQUEST_FILE
/* Check for the error condition */
if RC ~= 0 then do
REQUEST_MESSAGE TEXT '"An error occurred (user\n'||,
'probably pressed Cancel)"'
end
else do
REQUEST_MESSAGE TEXT '"You chose: '||RESULT||'"'
end
Common ARexx problems
=====================
ARexx problem 1
---------------
"I can't use strings with spaces in them."
Care must be taken when specifying string paramters when the string
contains space characters. Single quotes must be used around double
quotes to stop the string from being seen as many different strings.
Consider the following example:
REQUEST_MESSAGE TEXT "Hello"
ARexx would evaluate the string "Hello" and give ImageStudio the
following command to execute:
REQUEST_MESSAGE TEXT Hello
i.e. without the double quotes. In this example, REQUEST_MESSAGE
would do as expected. The problems start when strings have spaces in
them; consider the following:
REQUEST_MESSAGE TEXT "Hello world"
ARexx would evaluate the string "Hello world" and give ImageStudio
the following command to execute:
REQUEST_MESSAGE TEXT Hello world
which is not what is desired. The Hello becomes the TEXT value and
the world becomes the value of the next parameter (BUTTONTEXT in this
case). The result would be a requester with the text of "Hello" and a
button called "world". Now we must use the single quotes to stop ARexx
from evaluating the string:
REQUEST_MESSAGE TEXT '"Hello world"'
would send ImageStudio the following command:
REQUEST_MESSAGE TEXT "Hello world"
which shows that the whole string "Hello world" belongs to the TEXT
parameter.
ARexx problem 2
---------------
"I can't use AmigaDos commands in a script."
There is a bug which causes ImageStudio to sometimes crash the
machine if the output from AmigaDos command is not properly
re-directed. The stdin and stdout for all external CLI commands should
be redirected to the NIL: device.
For example:
address command 'rename ram:foo ram:bar'
could crash the machine if the rename fails (e.g. the file "ram:foo"
doesn't exist). To avoid this, use:
address command 'rename <NIL: >NIL: ram:foo ram:bar'
The failure will still be trapped by ARexx and sets RC to 10.
ARexx problem 3
---------------
"I can't run scripts from the ram disk."
This is due to ARexx scripts being treated by ARexx as external
commands. Command names may not contain spaces, and scripts in the ram
disk will be called something like `Ram Disk:MyScript.isrx', which is
not allowed.
To work around this, either move the script to a location without a
space in its filename or specify the ram disk as `ram:' rather than
`Ram Disk:'.
ARexx problem 4
---------------
"I can't set the same variable twice with VAR"
If you are able to return a value from a command into a given
variable name once in a program, but unable to do it again it's probably
due to ARexx evaluating your variable the second time it is used.
For example, the following won't work:
FILE_JOIN FILEPART '"Work:"' '"MyFile"' VAR fullname
FILE_JOIN FILEPART '"Work:"' '"MyOtherFile"' VAR fullname
because ARexx will evaluate `fullname' in the second FILE_JOIN, i.e.
ARexx will see the second FILE_JOIN as:
FILE_JOIN FILEPART "Work:" "MyFile" VAR Work:MyFile
The solution is to enclose the variable name in single quotes to
stop it from being evaluated, i.e. our second FILE_JOIN is written as:
FILE_JOIN FILEPART '"Work:"' '"MyOtherFile"' VAR 'fullname'
ARexx problem 5
---------------
"I can't get any ARexx script to run."
In order for ARexx to be available to ImageStudio, you must start
ARexx at startup time by including the line:
rexxmast >NIL:
in your `User-Startup' file in the `S:' directory. Normally this
line should be present in your User-Startup, but if you find no scripts
run from ImageStudio you must add this line manually.
ARexx tips
==========
ARexx tip 1
-----------
"How to turn stem arrays into strings."
It usually desirable for commands that return arrays to return the
values in a stem, making the return values easier to deal with. In some
cases it is neccessary to pass these values back to ImageStudio after
reading or altering them. As ImageStudio commands can't accept stems
directly, these stems have to be converted back into strings.
We suggest the following method, using the PALETTE_GET and
PALETTE_SET commands as examples of getting and setting an array of
values:
/* Get the current palette */
PALETTE_GET STEM OLDPALETTE.
/* Convert the stem to a parameter list */
NEWPALETTE = ''
do l = 0 to (OLDPALETTE.PALETTE.COUNT - 1)
NEWPALETTE = NEWPALETTE||' '||OLDPALETTE.PALETTE.l
end
/* Force the new palette back onto the image */
PALETTE_SET PALETTE NEWPALETTE REMAP
ARexx tip 2
-----------
"Shortening command names"
Using the current ARexx command interpreter within ImageStudio, it
is possible to specify a shorter version of each ARexx command. For
example, `OP' could be used as a synonym for `OPEN' and `RG' is a
synonym for `RGB_TO_HSV'. The following should be noted however:
* This behaviour may be removed in a future version of ImageStudio.
Therefore we recommend that this feature only be used to reduce
typing in the command shell (see Command_shell) and not be used in
ARexx scripts.
* If the shortened command name is ambiguous, the first matching com
mand will be executed. For example, if the shortened command
`REQUEST' is used, `REQUEST_DIR' will be executed.
Example scripts
===============
BalanceTest
-----------
Description
This script allows the user to see the result of changing the
brightness, contrast and gamma values over their full ranges.
An image is loaded in if one is not present already. The image is
then divided into 3 strips - the top, middle and bottom
representing changes to the balance, contrast and gamma
respectively. Depending on the number of divisions the user
chooses, each of the 3 strips is divided further horizontally and
each of the brightness, contrast and gamma values are applied
starting from -100 on the left to +100 on the right. An odd number
of horizontal divisions are used to leave a central, vertical area
of the image which remains unchanged.
Known bugs
None.
BatchConvert
------------
Description
This scripts allows the conversion of multiple images to be output
as one image format.
The script allows the following:
1. Saving of the converted image into a different location as the
source.
2. Choose any of the available image formats to save, with
controls over their subformat.
3. Automatic file renaming.
4. Automatic deleting of source images if different from the
destination image.
Known bugs
If the source and destination files are the same, but have
different filenames (e.g. `T:Bud2.gif' and `Ram:T/Bud2.gif') the
script will delete the source file (which will be the destination
file). To avoid this, make sure both filenames are both specified
in the same manner.
BatchProcess
------------
Description
This scripts allows the processing of multiple images to be output
as one image format. The script is based on `BatchConvert' (see
BatchConvert).
The commands to control the processing should be typed in to the
appropriate requester as though they were ARexx commands to be
executed in a script. For example:
SCALE 640 480
would scale each image to 640x480 pixels before saving out.
Multiple commands can be separated with a semi-colon `;', for
example:
SCALE 800 600;COLOURS 256 DITHER FS
would scale the image to 800x600 and then reduce to 256 colours
with Floyd-Steinberg dithering before saving out. Commands are
executed from left to right.
The script allows the following:
1. Saving of the processed image into a different location as the
source.
2. Choose any of the available image formats to save, with
controls over their subformat.
3. Automatic file renaming.
4. Application of multiple commands to process the image before
saving.
5. Automatic deleting of source images if different from the
destination image.
Known bugs
If the source and destination files are the same, but have
different filenames (e.g. `T:Bud2.gif' and `Ram:T/Bud2.gif') the
script will delete the source file (which will be the destination
file). To avoid this, make sure both filenames are both specified
in the same manner.
BatchProcessNotify
------------------
Description
This script starts a batch lot of processing to be performed when a
given file is changed or created; the script is based on
`BatchConvert' (see BatchProcess).
This is useful if you wish to convert the output from a program
that has generated multiple frames (e.g. a raytracer or landscape
renderer) into a format that can be compiled into an animation
(e.g. ILBM24 to HAM6).
The first thing the user must select is the filename of the final
file in the sequence. When this file has been created, ImageStudio
will start the processing of the images. This file may not of
course have been created yet, so the user will have to type the
name into the file requester.
After the user has specified the output format (see BatchProcess),
the script will wait for the specified file be created before
proceeding with the processing on all the files in the chosen
directory with the same basename as the selected final filename.
Known bugs
If the source and destination files are the same, but have
different filenames (e.g. `T:Bud2.gif' and `Ram:T/Bud2.gif') the
script will delete the source file (which will be the destination
file). To avoid this, make sure both filenames are both specified
in the same manner.
Example
The user wishes to convert the 24bit output files created by a
raytracer into HAM6 format, ready for compiling into an animation.
The animation is 200 frames and the files are numbered `pic.0001',
`pic.0002' etc... and are located in the `Work:Render' direc tory.
No extra processing is to be performed on the images.
Upon running the BatchProcessNotify script, the user enters
`Work:Render/pic.0200' as the final frame in the sequence and sets
the output file format to be IFF-ILBM, HAM6.
The script now waits for the final file to be created, and upon do
ing so, matches all files in the `Work:Render' directory that start
with the basename `pic.'. 200 files should be found. Each of these
files are loaded and saved as HAM6, before the script ends.
ConvolveTest
------------
Description
Applies a chosen set of convolution filters to an image.
A number of convolution filters are chosen and the image is tiled
depending on the number of filters chosen, each filter is applied
to each of the tiles.
Known bugs
1. The convolution filters chosen to apply *must* be taken from
the directory currently shown in the `Convolves' floating
palette. This is because convolution filters with the
CONVOLVE command are chosen by name, not filename (see
ARexx_CONVOLVE).
2. The tiling algorithm used isn't very smart, the number of
tiles vertically is the same as the number horizontally. This
can lead to almost half of the image being unaffected if the
number of chosen filters is just above the nearest square
number.
3. The maximum number of filters to be applied to the image is
100.
Crop512x512
-----------
Description
Removes blank area from unregistered images.
When a large image in loaded into the unregistered version of
ImageStudio, the actual image is only contained in the top-left
512x512 pixels of the buffer. This script crops away the blank
buffer to leave a buffer of only 512x512 pixels in size.
Known bugs
None.
Demo
----
Description
Demonstrates some of the features of the ImageStudio ARexx inter
face.
Simply follow the prompts to see the features being explained.
Known bugs
None.
RegionRecall
------------
Description
Sets a previously remembered region.
This script allows the region that was set with RegionStore (see
RegionStore) to be recalled as the active region for the current
image. The user is warned if there is already a currently selected
region which will be lost if the remembered region is recalled.
Known bugs
None.
RegionStore
-----------
Description
Remembers a region for future recall.
The region maybe recalled by using the RegionRecall (see
RegionRecall) script.
Known bugs
None.
ToIcon
------
Description
Resizes and remaps the image to that suitable as an icon.
The script allows the following:
1. Choosing of an alternative palette other than the default 4
colour Workbench palette.
2. Copying of the image into the clipboard, ready to be pasted
into IconEdit.
Known bugs
None.
ARexx commands
==============
More detailed information on each of the individual ARexx commands
can be found below.
BALANCE
-------
Command
BALANCE
Parameters template
BRIGHTNESS/N, CONTRAST/N, GAMMA/N, NORED/S, NOGREEN/S,
NOBLUE/S
Return template
None.
Description
This command allows the user to change the colour balance of the im
age. The user may select specify one of the BRIGHTNESS, CONTRAST
or GAMMA values to adjust - specifying more than one will only
result in the first operation being acted upon.
By default, the operation is applied to all the red, green and blue
values of the image. The user may stop any of the RGB channels
being affected by selecting any of the NORED, NOGREEN or NOBLUE
switches. Multiple switches may be used, but not all three
together.
See Show_balance, for a full description of altering the image's
colour balance.
Parameters
BRIGHTNESS
This adjusts the brightness / darkness of the image. Valid
values are between -100 (make everything black) to 100 (make
everything twice as bright).
CONTRAST
This adjusts the relative difference between dark and light
colours. Valid values are -100 (everything to mid-grey) to
100 (everything to extreme contrast).
GAMMA
This adjusts the gamma response of the image. Valid values
are -100 to 100.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following adjusts the gamma of the image by 10:
BALANCE GAMMA 10
The following darkens the green componant of the image by -20:
BALANCE BRIGHTNESS -20 NORED NOBLUE
Known bugs
None.
COLOURS
-------
Command
COLOURS
Parameters template
NUMCOLOURS/N, SIXTEENMILLION/S, COLOURCHOICE, DITHER
Return template
None.
Description
Allows the user to change the number of colours of the current im
age. The image can be changed to either 2-256 colours or 16 million
colours (24bit). Methods of colour choice and dithering are
available when reducing the number of colours in the image.
See Colours, for a full description of changing the number of
colours in the image.
Parameters
NUMCOLOURS/N
The number of colours desired for the image. Valid values are
2 to 256, the result will always be a colour-mapped image.
SIXTEENMILLION/S
In order to increase the number of possible colours in the
image to the maximum possible (16 million), the user should
specify this switch. The user may not specify this switch as
well as the NUMCOL OURS option.
COLOURCHOICE
This is a string which determines which method of colour
choice should be used to reduce the number of colours in an
image. At the present time, HECKBERT is the only available
option and will be used by default if no COLOURCHOICE is
specified.
DITHER
This string determines which method of dithering should be
used when reducing the number of colours in an image. Valid
strings are: NONE, FLOYD-STEINBERG or FS, STUCKI, JARVIS,
BURKES, SIERRA and STEVEN SON-ARCE. By default, no dithering
is used.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following reduces the image to 16 colours with Floyd-Steinberg
dithering:
COLOURS NUMCOLOURS 16 DITHER "FS"
The following increases the image to 24bits, allowing 16 million
possible colours:
COLOURS SIXTEENMILLION
Known bugs
None.
CONVOLVE
--------
Command
CONVOLVE
Parameters template
NAME/A
Return template
None.
Description
Applies the named convolution to the 24bit image. Convolution can
only be applied to 16 million colour (24bit) images.
See Show_convolves, for a full description of convolution filters.
Parameters
NAME/A
The name of the convolution filter as it appears in the "Show
convolves" floating palette.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following applies the "Blur high" convolution filter to the
current image:
CONVOLVE NAME '"Blur high"'
The following increases the image to 24bits if necessary, then
applies the "Edge detect" convolution filter:
IMAGEINFO_GET STEM IMAGEINFO.
if IMAGEINFO.DEPTH ~= 24 then do
COLOURS SIXTEENMILLION
end
CONVOLVE NAME '"Edge detect"'
Known bugs
None.
COPY
----
Command
COPY
Parameters template
None.
Return template
None.
Description
Copies the current image into the clipboard buffer.
See Copy, for a full description of copying images to the clip
board.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following copies the current image to the clipboard:
COPY
Known bugs
None.
CROP
----
Command
CROP
Parameters template
None.
Return template
None.
Description
Crops the image to the currently selected region. A region must be
selected for this command to work.
See Crop, for a full description of cropping images.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following crops the current image to the currently selected
region:
CROP
The following crops the current image to the currently selected
region only if a region exists:
REGION_GET STEM REGIONINFO.
if REGIONINFO.MINX ~= -1 then do
CROP
end
Known bugs
None.
EFFECT
------
Command
EFFECT
Parameters template
NAME/A, ARGS
Return template
None.
Description
Applies the named effect to the image. Optional arguments that the
effect may require can be passed via the ARGS parameter.
See Effects, for a full description of the available effects.
Parameters
NAME/A
The name of the effect to apply, as it appears in the
"Effects" floating palette.
ARGS
Any optional arguments that the desired effect may require.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following applies the "Negative" effect to the image:
EFFECT NAME "Negative"
The following pixelizes the image to a size of 4 pixels:
EFFECT NAME "Pixelize" ARGS '"PIXELSIZE 4"'
Known bugs
None.
FILES_MATCH
-----------
Command
FILES_MATCH
Parameters template
PATHPART/A, PATTERN
Return template
FILEPARTS/M
Description
Returns a list of files in a directory matching an optional
pattern.
Parameters
PATHPART/A
The path (directory) name from which the filenames should be
taken.
PATTERN
Optional file matching pattern, to allow the inclusion of
only spe cific filenames. By default, all the files in a
directory are returned.
Returns
FILEPARTS/M
An array of strings containing the matching filenames in the
given PATH.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets all the filenames from the "Pics" directory and
returns them in the stem FILENAMES.:
FILES_MATCH PATHPART "Pics" STEM FILENAMES.
The following gets all the filenames in the current directory with
a ".ilbm" or ".iff" filename extension:
FILES_MATCH PATHPART '""' PATTERN "#?.(ilbm|iff)" STEM FILENAMES.
The following gets all the filenames in the "S:" directory that
start with an "S" and puts them in pop up requesters:
FILES_MATCH PATHPART "S:" PATTERN "S#?" STEM FILENAMES.
do l = 0 to (FILENAMES.FILEPARTS.COUNT - 1)
REQUEST_MESSAGE BUTTONTEXT "More|Cancel" AUTOCANCEL,
TEXT '"'FILENAMES.FILEPARTS.l'"'
end
Known bugs
None.
FILE_JOIN
---------
Command
FILE_JOIN
Parameters template
PATHPART/A, FILEPART/A
Return template
FILE
Description
Joins the path part of a filename to the file part of a filename,
returning the full filename. Adds `/' and `:' where appropriate to
create a full filename.
Parameters
PATHPART/A
The path (directory) part of the filename to be created.
FILEPART/A
The file part of the filename to be created.
Returns
FILE
The full filename created from the path and file parts.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following creates the filename "Pics/HappyFace_240x250.bmp"
from the seperate path and fileparts - the result is put in a pop
up requester:
FILE_JOIN PATHPART "Pics" FILEPART "HappyFace_240x250.bmp"
REQUEST_MESSAGE TEXT '"'RESULT'"'
The following creates the filename "T:TempImage.jpg" from the
seperate path and fileparts (note how the '/' seperater is not
needed) - the result is put in a pop up requester:
FILE_JOIN PATHPART "T:" FILEPART "TempImage.jpg"
REQUEST_MESSAGE TEXT '"'RESULT'"'
Known bugs
None.
FILE_RENAME
-----------
Command
FILE_RENAME
Parameters template
FILE/A, FROM/A, TO/A
Return template
FILE
Description
Replaces the last occurrance of a given string in a filename with
another string. Useful for renaming filename extensions.
Note: *This command doesn't actually rename the file*, it simply
returns what the new filename should be.
Hint: To rename *any* filename extension to a chosen extension,
you can set "FROM ." and "TO .newextension". This removes any old
extension and replaces it with the given new extension. This can be
useful if you are converting a large number of different format
files to one format (see BatchConvert).
Parameters
FILE/A
The original filename to be renamed.
FROM/A
The string to remove from the old filename.
TO/A
The string to replace the FROM string in the filename.
Returns
FILE
The renamed filename. If no FROM string was found in the
original filename, the original filename is returned with the
new TO string appended.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following renames the filename "Zebra_250x250.pcx" to
"Zebra_250x250.ilbm", the final filename is placed in RESULT:
FILE_RENAME FILE "Zebra_250x250.pcx" FROM ".pcx" TO ".ilbm"
The following appends ".out" to the filename "pic.0001":
FILE_RENAME FILE "pic.0001" FROM "XXX" TO ".out"
Known bugs
None.
FILE_SPLIT
----------
Command
FILE_SPLIT
Parameters template
FILE/A
Return template
PATHPART, FILEPART
Description
Splits the given filename into seperate path and file parts.
Parameters
FILE/A
The full filename to be split.
Returns
PATHPART
The path (directory) part of the filename.
FILEPART
The file part of the filename.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following seperates the filename "Pics/HappyFace_240x250.bmp"
into seperate path and fileparts - the result is put in a pop up
requester:
FILE_SPLIT FILE "Pics/HappyFace_240x250.bmp" STEM FILENAME.
REQUEST_MESSAGE TEXT '"Path:'FILENAME.PATHPART,
'File:'FILENAME.FILEPART'"'
The following seperates the filename "T:TempImage.jpg" into
seperate path and fileparts - the result is put into the default
settings of a file requester:
FILE_SPLIT FILE "T:TempImage.jpg" STEM FILENAME.
REQUEST_FILE PATHPART '"'FILENAME.PATHPART'"',
FILE '"'FILENAME.PATHPART'"'
Known bugs
None.
FULL_IMAGE
----------
Command
FULL_IMAGE
Parameters template
None.
Return template
None.
Description
Displays the full image in the preview window.
See Full_image, for a full description of this command.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following displays the full image in the preview window:
FULL_IMAGE
Known bugs
None.
GUI_BLOCK
---------
Command
GUI_BLOCK
Parameters template
None.
Return template
None.
Description
Blocks all input to any open ImageStudio windows. This command is
used to stop the user from entering any more input into the
ImageStudio windows whilst an ARexx script is running. If the
script has been started from ImageStudio (i.e. from the "Scripts"
floating palette), all the GUI blocking / unblocking is handled
automatically - the GUI is blocked when the script starts and
unblocked when it finishes.
If the script is started externally (i.e. from another ARexx
program or from the CLI using `rx'), the user should block the GUI
if they think the ARexx is going to spend a long time processing
some in formation. The GUI is still automatically blocked when a
requester is opened however.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following blocks all input to the ImageStudio GUI:
GUI_BLOCK
Known bugs
None.
GUI_UNBLOCK
-----------
Command
GUI_UNBLOCK
Parameters template
None.
Return template
None.
Description
Unblocks all input to any open ImageStudio windows after a
GUI_BLOCK command. If the script has been started from ImageStudio
(i.e. from the "Scripts" floating palette), all the GUI blocking /
unblocking is handled automatically - the GUI is blocked when the
script starts and unblocked when it finishes.
If the scripts is started externally (i.e. from another ARexx pro
gram or from the CLI using `rx'), the user should unblock the GUI
after a GUI_BLOCK command has been issued. The GUI is still
automatically unblocked after a requester has been satisfied
however.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following unblocks all input to the ImageStudio GUI:
GUI_UNBLOCK
Known bugs
None.
HELP
----
Command
HELP
Parameters template
COMMAND
Return template
COMMANDDESC, COMMANDLIST/M
Description
Returns help on a given ARexx command. This command is meant mainly
for use with the command shell (see Command_shell), as it is of
very little use within a script. Both the command's parameter and
return templates are returned.
Parameters
COMMAND
The ARexx command to obtain help on.
Returns
COMMANDDESC
The parameter template.
COMMANDLIST/M
The result template.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets help on the ARexx OPEN command:
HELP OPEN
The following gets help on the HELP command:
HELP HELP
Known bugs
None.
HSV_TO_RGB
----------
Command
HSV_TO_RGB
Parameters template
H/N/A, S/N/A, V/N/A
Return template
R/N, G/N, B/N
Description
Converts a HSV colour value into a RGB colour value.
See Colour representations, for more details on RGB and HSV colour
representations.
Parameters
H/N/A
The hue value of the colour to convert. Valid values are 0 to
360.
S/N/A
The saturation value of the colour to convert. Valid values
are 0 to 100.
V/N/A
The value of the colour to convert. Valid values are 0 to 100.
Returns
R/N
The red componant value of the colour.
G/N
The green componant value of the colour.
B/N
The blue componant value of the colour.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following converts yellow from HSV to RGB representation,
putting the result in RESULT:
HSV_TO_RGB 60 100 100
The following converts mid-grey from HSV to RGB representation,
putting the result in the stem COLOUR.:
HSV_TO_RGB 0 0 49 STEM COLOUR.
Known bugs
None.
IMAGEINFO_GET
-------------
Command
IMAGEINFO_GET
Parameters template
None.
Return template
WIDTH/N, HEIGHT/N, DEPTH/N, FILE, MODEID/N, CHANGED/N
Description
Returns information about the current image. If no image is
currently loaded, -1 is returned in all the numeric fields.
Parameters
None.
Returns
WIDTH/N
The width of the image in pixels, -1 if no image is loaded.
HEIGHT/N
The height of the image in pixels, -1 if no image is loaded.
DEPTH/N
The colour depth of the image, -1 if no image is loaded.
Returns 1 to 8 for 2 to 256 colour images, 24 for 16 million
colour images.
FILE
The full filename of the current image.
MODEID/N
The current screenmode of the image. This number is not meant
to be interpreted directly, but can be used to be passed to
the screenmode requester (see ARexx_REQUEST_SCREENMODE).
When the image loaded is a non IFF-ILBM image, this
screenmode value is "guessed" at by ImageStudio to be the
closest Amiga equivalent based on the image's dimensions.
CHANGED/N
A numeric value, taking the value 1 to represent a change in
the current project or 0 for no change.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the current image's information and returns it
in the stem IMAGE.:
IMAGEINFO_GET STEM IMAGE.
The following gets the current image's info and opens a screenmode
requester with the current screenmode if an image is loaded:
IMAGEINFO_GET STEM IMAGE.
if IMAGE.WIDTH ~= -1 then do
REQUEST_SCREENMODE MODEID IMAGE.MODEID
end
Known bugs
None.
IMAGEINFO_SET
-------------
Command
IMAGEINFO_SET
Parameters template
MODEID/N
Return template
None.
Description
Sets information about the current image. Currently, only the
image's screenmode can be set.
Parameters
MODEID/N
The current screenmode ID of the image.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sets the current image's screenmode to LoRes.
IMAGEINFO_SET MODEID 0
The following opens up a screenmode requester and allows the user
to choose the screenmode of the current image:
REQUEST_SCREENMODE STEM SCREENMODEINFO.
IMAGEINFO_SET MODEID SCREENMODEINFO.MODEID
Known bugs
None.
NOTIFY_DIR
----------
Command
NOTIFY_DIR
Parameters template
PATHPART/A
Return template
FILEPART, ACTION
Description
Monitors the specified directory and returns when a file is either
updated or added to the directory. The affected filename is
returned as well as the action that had been performed (either
updated or added).
Whilst the command is waiting for any change in the specified
directory, the fuelgauge will flash and the user may press the
`Abort' button on the infobar to cancel the operation.
Parameters
PATHPART
The path (directory) to be monitored.
Returns
FILEPART
The filename of the file that has been changed; the filename
returned is without the full pathname. See ARexx_FILE_JOIN,
for information on how to add the path part of the filename
to create a full filename.
ACTION
A string containing a descripion of the action performed on
FILE, either "ADDED" if the file is new to the directory or
"UPDATED" if the file has been updated since the notify
started.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following monitors the ram disk for any change, returning any
change in the NOTIFYINFO. stem:
NOTIFY_DIR PATHPART "ram:" STEM NOTIFYINFO.
The following monitors the "Pics" directory for any change and pops
up a requester informing the user of what has happened:
NOTIFY_DIR PATHPART "Pics" STEM NOTIFYINFO.
REQUEST_MESSAGE TEXT '"'NOTIFYINFO.FILEPART||' has been '||,
NOTIFYINFO.ACTION'"'
Known bugs
1. AmigaDos won't notify us if a file is deleted from the
directory.
2. If many files are added / updated in the directory quickly,
NOTIFY_DIR may not necessarily return the first changed file.
The same is true if the a file is created with an icon,
NOTIFY_DIR may return the name of the ".info" file.
3. File notification is not implemented on all filesystems
(notably some network filesystems). No problems occur with
either the stand ard OFS or FFS filesystems.
NOTIFY_FILE
-----------
Command
NOTIFY_FILE
Parameters template
FILE/A
Return template
None.
Description
Waits for a change in the specified file. The function will return
if either a new file by the given name is created, or if the file
is updated. Unlike NOTIFY_DIR (see ARexx_NOTIFY_DIR), NOTIFY_FILE
also returns if the specified file is deleted.
Whilst the command is waiting for any change in the specified file,
the fuelgauge will flash and the user may press the `Abort' button
on the infobar to cancel the operation.
This function can be used to trigger ImageStudio to perform a given
set of operations when the specified file has been created. For
example, if 50 frames of an animation were being rendered by a
ray-tracer then ImageStudio could be told to wait for the last
frame to be created an then convert them all to HAM format.
Parameters
FILE
The file to be monitored.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following monitors the file "Pics/CheetahFace250x200.ilbm" for
any change:
NOTIFY_FILE "Pics/CheetahFace250x200.ilbm"
The following waits for the 50th frame in the sequence "Render." to
be created in the "Work:RayTrace":
NOTIFY_FILE "Work:RayTrace/Render.050"
Known bugs
File notification is not implemented on all filesystems (notably
some network filesystems). No problems occur with either the stand
ard OFS or FFS filesystems.
OPEN
----
Command
OPEN
Parameters template
FILE/A, FORMAT, ARGS, FORCE/S
Return template
None.
Description
Loads the specified file into ImageStudio. Most file formats are
automatically recognised by the program, but it is possible to
specify extra information with the FORMAT and ARGS parameters.
Parameters
FILE
The filename of the file to be loaded.
FORMAT
Most file formats are automatically recognised by
ImageStudio, but some raw formats need to be specified. If
the file to be loaded is known to be a raw format, this
parameter should be used to specify the file format. See File
formats, for more information on raw file formats.
ARGS
Some file formats require extra information to be specified a
load time, this parameter should be used to specify more
information. See File formats, for more information on extra
arguments allowed by the loaders.
FORCE/S
By default the user will be warned if they are about to
overwrite the current project. By specifying FORCE, the user
is not warned.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following opens the file "Pics/CheetahFace250x200.ilbm":
OPEN "Pics/CheetahFace250x200.ilbm"
Known bugs
None.
PALETTE_GET
-----------
Command
PALETTE_GET
Parameters template
None.
Return template
PALETTE/N/M
Description
Gets the palette information from the current image.
Parameters
None.
Returns
PALETTE/N/M
An array of the colours in the palette, ordered red, green
then blue. Check PALETTE.COUNT for the number of entries in
the array, divide this value by 3 to get the number of
colours in the palette.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the palette from the current image and returns
it in the PALETTE. stem:
PALETTE_GET STEM PALETTE.
The following gets the palette from the current image (if possible)
and puts the first colour value in a requester:
IMAGEINFO_GET STEM IMAGEINFO.
if IMAGEINFO.DEPTH ~= 24 then do
PALETTE_GET STEM PALETTE.
numcolours = PALETTE.PALETTE.COUNT / 3
REQUEST_MESSAGE TEXT '"'numcolours||' colours, colour 0 = '||,
PALETTE.PALETTE.0||','||PALETTE.PALETTE.1||','||,
PALETTE.PALETTE.2||'"'
end
else do
REQUEST_MESSAGE TEXT '"Image has no palette."'
end
Known bugs
None.
PALETTE_LOAD
------------
Command
PALETTE_LOAD
Parameters template
FILE/A, DITHER
Return template
None.
Description
Loads and remaps a palette onto the current image. Dithering is
also allowed to get a better approximation with the new palette.
Parameters
FILE/A
The filename of the palette file to load.
DITHER
A string containing the name of the dither to apply when
applying the new palette. The same dither names as the
COLOURS command are used (see ARexx_COLOURS). By default, no
dithering is applied.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following loads a general 256 colour palette onto the image:
PALETTE_LOAD FILE "Palettes/General256.palette"
The following loads a general 16 colour palette with
Floyd-Steinberg dithering onto the image:
PALETTE_LOAD FILE "Palettes/General16.palette" DITHER "FS"
Known bugs
None.
PALETTE_SAVE
------------
Command
PALETTE_SAVE
Parameters template
FILE/A
Return template
None.
Description
Saves the palette of the current image out to disk. The image must
be colour-mapped for this operation to work.
Parameters
FILE/A
The filename of the palette file to save.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following saves the current image's palette to the ram disk:
PALETTE_SAVE FILE "ram:Image.palette"
The following only saves out the palette of the current image if
the current image is colour-mapped:
IMAGEINFO_GET STEM IMAGEINFO.
if IMAGEINFO.DEPTH ~= 24 then do
PALETTE_SAVE FILE "Image.palette"
end
Known bugs
None.
PALETTE_SET
-----------
Command
PALETTE_SET
Parameters template
PALETTE/N/M/A, REMAP/S
Return template
None.
Description
Forces the array of numbers as the current palette for the image.
The depth of the resultant image is taken from the number of
entries in the array. This is useful for adding colours into the
current image's palette.
Parameters
PALETTE/N/M/A
The array of numbers that will build the palette. The total
number of elements in the array determines the number of
palette entries and the depth of the resultant images. The
entries in the array are arranged colour0_red, colour0_green,
colour0_blue, colour1_red etc... The values of the red, green
and blue values are 0 to 255.
REMAP
By default, the given palette is forced up on the current
image. By specifying the REMAP switch, the image can be
remapped to best fit the new palette.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sets the current image to black and white, remapping
as best as possible:
PALETTE_SET PALETTE "0 0 0 255 255 255" REMAP
The following reduces the number of colours in the image to 29,
then sets the top 3 colours to be red, white and blue. This is an
example of how the returned stem value can be turned into a list of
parameters for another command:
/* Reduce the number of colours */
COLOURS NUMCOLOURS 29 DITHER "FS"
/* Get the current palette */
PALETTE_GET STEM OLDPALETTE.
/* Set the top 3 colours to red, white and blue */
OLDPALETTE.PALETTE.87 = 255 /* Red */
OLDPALETTE.PALETTE.88 = 0
OLDPALETTE.PALETTE.89 = 0
OLDPALETTE.PALETTE.90 = 255 /* White */
OLDPALETTE.PALETTE.91 = 255
OLDPALETTE.PALETTE.92 = 255
OLDPALETTE.PALETTE.93 = 0 /* Blue */
OLDPALETTE.PALETTE.94 = 0
OLDPALETTE.PALETTE.95 = 255
/* Convert the stem to a parameter list */
NEWPALETTE = ''
do l = 0 to (OLDPALETTE.PALETTE.COUNT - 1)
NEWPALETTE = NEWPALETTE||' '||OLDPALETTE.PALETTE.l
end
/* Force the new palette onto the image */
PALETTE_SET PALETTE NEWPALETTE REMAP
Known bugs
None.
PALETTE_SORT
------------
Command
PALETTE_SORT
Parameters template
FROM/N, TO/N, LIGHTTODARK/S
Return template
None.
Description
Sorts the colours in the palette into ascending / descending order
of brightness. The whole palette can be sorted or a selected range.
The colours in the palette are numbered from zero, so a 32 colour
image would have palette entries 0 to 31 inclusive.
The image in automatically remapped to the new palette after the
operation.
Parameters
FROM/N
The first colour in the palette to sort from. By default this
is zero.
TO/N
The last colour in the palette to sort to. By default this is
the last colour in the image's palette.
LIGHTTODARK/S
By default the palette is sorted from dark to light. This
option allows the palette to be sorted light to dark.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sorts the colours in the image's palette dark through
to light:
PALETTE_SORT
The following sorts the lower 32 colours in a 64 colour image from
light to dark:
PALETTE_SORT FROM 0 TO 31 LIGHTTODARK
Known bugs
None.
PASTE
-----
Command
PASTE
Parameters template
FORCE/S
Return template
None.
Description
Pastes the image in the clipboard into the program.
Parameters
FORCE/S
By default the user is warned if the the current project is
unsaved and they are about to overwrite it. This parameter
will not warn the user and overwrite the project regardless.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following pastes the image in the clipboard, warning the user
if the current project isn't saved:
PASTE
The following pastes the image in the clipboard with no warning to
the user if the current project isn't saved:
PASTE FORCE
Known bugs
With v2.0.x, if the user presses `Abort' when the file is being
pasted, an error message is not returned and so the ARexx script as
sumes the file pasted OK. This will be fixed when the loaders /
savers become external modules.
PREF_GET
--------
Command
PREF_GET
Parameters template
NAME/A
Return template
VALUE
Description
Allows the user to read any of the preferences values currently in
use by the program.
See Prefs, for a full description of the available preference
values.
Parameters
NAME/A
The name of the preference whose value should be returned. The
tooltype name is given here, so to read the virtual memory
pagesize for example, NAME would be PAGESIZE.
If the preference name is not found, an error is returned.
Returns
VALUE
The value of the preference. If the preference is a string,
VALUE is the string value, if the preference is numeric,
VALUE is the number value and if the preference is boolean,
VALUE is either the value 1 for a positive setting ("YES" or
"ON") or 0 for a negative setting ("NO" or "OFF").
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following finds the current virtual memory pagesize:
PREF_GET NAME "PAGESIZE"
say 'The pagesize is 'RESULT * 1024' bytes'
The following detects whether the preview dithering is being used:
PREF_GET NAME "PREVIEWDITHER"
if RESULT == 1 then do
say 'Preview dithering is ON'
end
else do
say 'Preview dithering is OFF'
end
Known bugs
None.
PREF_SET
--------
Command
PREF_SET
Parameters template
NAME/A, VALUE/A
Return template
None.
Description
Allows the user to set any of the preferences values currently in
use by the program. Changing some preference variables may have no
effect until the next time the program is run.
See Prefs, for a full description of the available preference
values.
Parameters
NAME/A
The name of the preference whose value should be changed. The
tooltype name is given here, so to set the virtual memory
pagesize for example, NAME would be PAGESIZE.
If the preference name is not found, an error is returned.
VALUE/A
The desired value of the preference. If the preference is a
string, VALUE should be a string value, if the preference is
numeric, VALUE should be a number value. If the preference is
boolean, VALUE can be either the strings "YES" or "ON" to set
a positive value, "NO" or "OFF" to set a negative value.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following turns the preview redraw off:
PREF_SET NAME "PREVIEWREDRAW" VALUE "OFF"
The following sets the virtal memory pagesize to be 200K:
PREF_SET NAME "PAGESIZE" VALUE 200
Known bugs
None.
QUIT
----
Command
QUIT
Parameters template
FORCE/S
Return template
None.
Description
Quits the program. By using the FORCE option, the program can be
forced to quit without warning the user.
The program cannot be quit by issuing the QUIT command from the
command shell.
Parameters
FORCE/S
By default the user is warned if the program is about to quit
and the current project remains unsaved. Specifying this
parameter will force the program to quit regardless.
Returns
Absolutely nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following quits the program, warning the user if the current
project is unsaved:
QUIT
The following quits the program regardless of the status of the
current project:
QUIT FORCE
Known bugs
None.
REDO
----
Command
REDO
Parameters template
None.
Return template
None.
Description
Re-does the last UNDO operation (see ARexx_UNDO).
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following re-does the last UNDO operation:
REDO
Known bugs
None.
REDRAW
------
Command
REDRAW
Parameters template
None.
Return template
None.
Description
Forces a redraw of the image in the preview window. This is not
normally needed, as all the redrawing is done automatically
however it could be used if the PREVIEWREDRAW preference is
changed within a script.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following forces a redraw of the image in the preview window:
REDRAW
The following forces a redraw of the image after the preview redraw
has been turned off with the PREVIEWREDRAW preference:
PREF_SET NAME "PREVIEWREDRAW" VALUE "OFF"
REDRAW
Known bugs
None.
REGION_CLEAR
------------
Command
REGION_CLEAR
Parameters template
None.
Return template
None.
Description
Removes the currently selected region, if one exists. No error is
given if a region doesn't exist.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following clears the currently selected region:
REGION_CLEAR
The following checks that a region is selected before trying to
clear it:
REGION_GET STEM REGIONINFO.
if REGIONINFO.MINX ~= -1 then do
REGION_CLEAR
end
Known bugs
None.
REGION_GET
----------
Command
REGION_GET
Parameters template
None.
Return template
MINX/N, MINY/N, MAXX/N, MAXY/N, WIDTH/N, HEIGHT/N
Description
Gets the current region dimensions from the image. If no region is
selected, -1 is returned in all the fields.
The values returned are the values of all the pixels inside the
selected region. For example, if the top left pixel only of the
image was selected the following values would be returned:
MINX = 0
MINY = 0
MAXX = 0
MAXY = 0
WIDTH = 1
HEIGHT = 1
Parameters
None.
Returns
MINX/N
The left-most pixel included in the selected region, -1 if no
region is selected.
MINY/N
The top-most pixel included in the selected region, -1 if no
region is selected.
MAXX/N
The right-most pixel included in the selected region, -1 if no
region is selected.
MAXY/N
The bottom-most pixel included in the selected region, -1 if
no region is selected.
WIDTH/N
The width of the selected region, -1 if no region is selected.
HEIGHT/N
The height of the selected region, -1 if no region is
selected.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following gets the currently selected region and returns the
value in the REGIONINFO. stem:
REGION_GET STEM REGIONINFO.
The following checks that a region is selected, popping up an
message requester:
REGION_GET STEM REGIONINFO.
if REGIONINFO.MINX ~= -1 then do
REQUEST_MESSAGE TEXT '"Width,Height = '||REGIONINFO.WIDTH||,
','||REGIONINFO.HEIGHT||'"'
end
else do
REQUEST_MESSAGE TEXT '"No region selected"'
end
Known bugs
None.
REGION_SET
----------
Command
REGION_SET
Parameters template
None.
Return template
XSTART/N, YSTART/N, TO/S, XEND/N, YEND/N
Description
Sets the selected region of the image. The region can either be
specifed by the co-ordinates of its corners or by its width, height
and position.
Parameters
XSTART/N
The left-most co-ordinate included in the region.
YSTART/N
The top-most co-ordinate included in the region.
TO/S
By default the region is specified by the co-ordinates of its
top-left corners and its width and height. By using the TO
parameter, the region can be specified with the lower-bottom
co-ordinate of the region.
XEND/N
The width of the region. If the TO parameter is used, this
value is used to specify the right-most pixel included by the
region.
YEND/n
The height of the region. If the TO parameter is used, this
value is used to specify the bottom-most pixel included by
the region.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following sets the selected region to have it's top-left corner
at (10,20) with a width of 30 and height of 40:
REGION_SET 10 20 30 40
The following sets the selected region to have it's top-left corner
at (50,60) and its bottom-right corner to include (70,80):
REGION_SET 50 60 TO 70 80
Known bugs
None.
REQUEST_DIR
-----------
Command
REQUEST_DIR
Parameters template
PATHPART, TITLE
Return template
PATHPART
Description
Opens a directory requester, allowing the user to choose a
directory name.
The other ImageStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all ImageStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap this
error, global error checking must be turned off. See Error
checking, for more information.
Parameters
PATHPART
The default path name to put in the requester.
TITLE
The text for the title bar of the requester.
Returns
PATHPART
The selected path from the requester.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem.
Example
The following puts up a directory requester, with the results being
put in the DIRINFO. stem:
REQUEST_DIR STEM DIRINFO.
The following puts up a directory requester with a default
directory of "T:", the result being printed in a message requester:
REQUEST_DIR PATHPART "T:" STEM DIRINFO.
REQUEST_MESSAGE TEXT '"You chose '||DIRINFO.PATHPART||'"'
Known bugs
None.
REQUEST_FILE
------------
Command
REQUEST_FILE
Parameters template
PATHPART, FILEPART, PATTERN, TITLE
Return template
FILE
Description
Opens a file requester, allowing the user to choose a filename.
The other ImageStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all ImageStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap this
error, global error checking must be turned off. See Error
checking, for more information.
Parameters
PATHPART
The default path name to put in the requester.
FILEPART
The default filename to put in the requester.
PATTERN
An AmigaDos pattern matching pattern, will only show files in
the requester which match the given pattern. By default, all
files are shown.
TITLE
The text for the title bar of the requester.
Returns
FILE
The selected filename from the requester, the filename
consists of both the FILEPART and PATHPART parts.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem.
Example
The following puts up a file requester, with the results being put
in the FILEINFO. stem:
REQUEST_FILE STEM FILEINFO.
The following puts up a file requester with the result being
printed in a message requester. The default file is
"Pics/HappyFace240x250.bmp":
REQUEST_FILE PATHPART "Pics" FILEPART "HappyFace240x250.bmp",
STEM FILEINFO.
REQUEST_MESSAGE TEXT '"You chose '||FILEINFO.FILE||'"'
The following will only show files with a ".ilbm" file extension:
REQUEST_FILE PATTERN "#?.ilbm"
Known bugs
None.
REQUEST_LIST
------------
Command
REQUEST_LIST
Parameters template
STRINGS/M/A, TITLE
Return template
NUMBER/N, STRING
Description
Opens a requester containing a list of options for the user to
choose.
The other ImageStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all ImageStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap this
error, global error checking must be turned off. See Error
checking, for more information.
Parameters
STRINGS/M/A
The a list of string options for the user to choose.
TITLE
The text for the title bar of the requester.
Returns
NUMBER/N
The number in the list of the selected string. The strings
are num bered from zero, so selecting the first choice in the
list would set NUMBER to 0.
STRING
The selected string.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, or the user can
celled requester, or no choice was made. rc2 will contain a string
describing the problem.
Example
The following puts up a list requester, with the results being put
in the LISTINFO. stem:
REQUEST_LIST STRINGS "IFF-ILBM" "PCX" "BMP" STEM LISTINFO.
The following puts up a list requester, the result being printed in
a message requester:
REQUEST_LIST STRINGS "First" "Second" "Third" STEM LISTINFO.
REQUEST_MESSAGE TEXT '"You chose '||LISTINFO.STRING||','||,
' option '||LISTINFO.NUMBER'"'
Known bugs
None.
REQUEST_MESSAGE
---------------
Command
REQUEST_MESSAGE
Parameters template
TEXT/A, BUTTONTEXT, AUTOCANCEL/S, TITLE
Return template
NUMBER/N
Description
Opens a general purpose message requester. Simple messages can be
presented to the user for them to "OK" them. OK / Cancel requesters
can be built with this requester, as well a complex multiple choice
requesters.
When designing requesters, it is worth remembering the following
rules:
1. The "Negative" response should be placed on the far right-hand
button. For example, the `Cancel' button should be placed
here.
2. The "Positive" response should be placed on the far left-hand
but ton. For example, the `OK' button should be placed here.
3. Try to word your requesters to keep the positive and negative
text as "OK" and "Cancel". Using options like "Go to it" and
"Stop right here" doesn't make for a very intuitive interface.
4. Keep the request text short. The user shouldn't have to read a
screen full of text to find out what to do next.
5. You should *NEVER* swap the "OK" and "Cancel" buttons around.
6. The last point is *VERY* important.
The other ImageStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
If the AUTOCANCEL option is used and the user presses `Cancel', an
error message is returned. For the script to trap this error,
global error checking must be turned off. See Error checking, for
more information.
Parameters
TEXT/A
The text to put into the requester. The text may contain
multiple lines by including the `\n' characters in the string
(see examples below).
BUTTONTEXT
The text for the buttons of the requester. The different
buttons are seperated with a `|' character (i.e. BUTTONTEXT
"OK|Cancel"). By default, only an "OK" button is placed in
the requester.
AUTOCANCEL/S
By default REQUEST_MESSAGE simply returns the number of the
button that the user selected. If the requester is of the OK
/ Cancel variety, specifying the AUTOCANCEL switch allows the
requester to stop the script should the user press `Cancel'.
TITLE
The text for the title bar of the requester.
Returns
NUMBER
The number of the selected button. If the requester has one
button, NUMBER is set to 0. For more that one button, the
right-most button sets NUMBER to 0, with the buttons being
numbered from 1 upwards working left to right. For example,
with a BUTTONTEXT of "OK|Save first|Cancel", "OK" would
return 1, "Save first" would return 2 and "Cancel" would
return 0.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem. rc will also be set to 10 if the
AUTOCANCEL option is used and the user selects `Cancel'.
Example
The following puts up a message requester:
REQUEST_MESSAGE TEXT '"Operation finished"'
The following puts up a OK / Cancel requester, stopping the script
if the user selects `Cancel':
REQUEST_MESSAGE TEXT '"Continue ?"' BUTTONTEXT "OK|Cancel",
AUTOCANCEL
The following shows a multiple choice requester, followed by a
requester showing which option was chosen:
REQUEST_MESSAGE TEXT '"Choose an option..."',
BUTTONTEXT "First|Second|Third"
REQUEST_MESSAGE TEXT '"You chose option '||RESULT||'"'
The following shows a message requester with multiple lines of text
using the `\n' characters:
REQUEST_MESSAGE TEXT '"Top line\nMiddle line\nBottom line"'
Known bugs
None.
REQUEST_MULTIFILE
-----------------
Command
REQUEST_MULTIFILE
Parameters template
PATHPART, FILEPART, PATTERN, TITLE
Return template
FILES/M
Description
Opens a file requester, allowing the user to choose multiple filena
mes.
The other ImageStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all ImageStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap this
error, global error checking must be turned off. See Error
checking, for more information.
Parameters
PATHPART
The default path name to put in the requester.
FILEPART
The default filename to put in the requester.
PATTERN
An AmigaDos pattern matching pattern, will only show files in
the requester which match the given pattern. By default, all
files are shown.
TITLE
The text for the title bar of the requester.
Returns
FILES/M
The selected filenames from the requester, the filenames
consists of both the FILEPART and PATHPART parts.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem. rc will also be set to 10 if no files are chosen.
Example
The following puts up a multifile requester, with the results being
put in the MULTIFILEINFO. stem:
REQUEST_MULTIFILE STEM MULTIFILEINFO.
The following puts up a multifile requester, with a default path of
"Pics" and loops through all the selected files by putting them in
message requesters:
REQUEST_MULTIFILE PATHPART "Pics" STEM MULTIFILENFO.
do l = 0 to (MULTIFILENFO.FILES.COUNT - 1)
REQUEST_MESSAGE TEXT '"'MULTIFILENFO.FILES.l'"',
BUTTONTEXT '"More...|Cancel"' AUTOCANCEL
end
Known bugs
If no file is chosen, the command returns a "user cancelled" error.
This is normal.
REQUEST_MULTIVALUE
------------------
Command
REQUEST_MULTIVALUE
Parameters template
STRINGS/M, TITLE
Return template
STRINGS/M
Description
Opens a multivalue requester, allowing the user to change any of
the listed values.
The other ImageStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all ImageStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap this
error, global error checking must be turned off. See Error
checking, for more information.
Parameters
STRINGS/M
A list of strings with the values to display in the
requester. The strings are grouped in pairs, the first string
of the pair being the text for the requester, the second
being the default value for that string.
For example, the following would place width and height
values in the requester, with default values of 640 and 480
respectively:
STRINGS "Width" "640" "Height" "480"
If there isn't an even number of strings, an error is
returned.
TITLE
The text for the title bar of the requester.
Returns
STRINGS/M
A list of strings with the values to display in the
requester. The strings are grouped in pairs, the first string
of the pair being the text for the requester, the second
being the returned value for that string.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem. rc will also be set to 10 if no files are chosen.
Example
The following puts up a multivalue requester, allowing the user to
change the width, height and depth of an image. The result is put
in the MULTIVALUEINFO. stem:
REQUEST_MULTIVALUE "Width" "640" "Height" "480",
STEM MULTIVALUEINFO.
The following puts up a multivalue requester, allowing the user to
change the name and depth of an image. The result is put displayed
in a message requester and the values recycled until the user can
cels the requesters:
INSTRINGS = 'Name ImageName.bmp Depth 4'
do forever
REQUEST_MULTIVALUE STRINGS INSTRINGS STEM MULTIVALUEINFO.
REQUEST_MESSAGE TEXT BUTTONTEXT "OK|Cancel" AUTOCANCEL,
TEXT '"Name: '||MULTIVALUEINFO.STRINGS.1||'\n'||,
'Depth : '||MULTIVALUEINFO.STRINGS.3||'"'
/* Construct the new INSTRINGS */
INSTRINGS = ''
do l = 0 to (MULTIVALUEINFO.STRINGS.COUNT - 1)
INSTRINGS = INSTRINGS||' '||MULTIVALUEINFO.STRINGS.l
end
end
Known bugs
None.
REQUEST_SCREENMODE
------------------
Command
REQUEST_SCREENMODE
Parameters template
MODEID/N, WIDTH/N, HEIGHT/N, OVERSCAN/N, DEPTH/N,
GADS_ENABLED/S, MAXDEPTH/N, MINWIDTH/N, MINHEIGHT/N
Return template
MODEID/N, WIDTH/N, HEIGHT/N, OVERSCAN/N, DEPTH/N, TEXT
Description
Opens a screenmode requester, allowing the user to select an Amiga
screenmode. By specifying the GADS_ENABLED, the user may also
select the width, height, depth and overscan values for the
screenmode.
The other ImageStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all ImageStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap this
error, global error checking must be turned off. See Error
checking, for more information.
Parameters
MODEID/N
The default screenmode ID for the requester which will be
selected in the requester. By default, LORES is selected.
WIDTH/N
The default screen width value to put in the requester. By
default, the default width of the selected screenmode is used.
HEIGHT/N
The default screen height value to put in the requester. By
default, the default height of the selected screenmode is
used.
OVERSCAN/N
The default overscan value to put in the requester. The
following values are valid: 1 for text size, 2 for graphics
size, 3 for extreme and 4 for maximum overscan. By default,
text size is used.
DEPTH/N
The default depth value to put in the requester. By default,
a depth of 2 is used.
GADSENABLED/S
By default the screenmode requester only allows the selecting
of the screenmode. By using this switch, the user may also
set the width, height, overscan and depth of the screenmode.
MAXDEPTH/N
The maximum depth allowed by the depth gadget. This value is
only relevant to the internal screenmode requester.
MINWIDTH/N
The minimum allowable width of the screenmode.
MINHEIGHT/N
The minimum allowable height of the screenmode.
Returns
MODEID/N
The chosen screenmode ID.
WIDTH/N
The screen width chosen in the requester. This value is only
set if the GADSENABLED switch is used.
HEIGHT/N
The screen height chosen in the requester. This value is only
set if the GADSENABLED switch is used.
OVERSCAN/N
The overscan value chosen in the requester. The following
values are returned: 1 for text size, 2 for graphics size, 3
for extreme and 4 for maximum overscan. This value is only
set if the GADSENABLED switch is used.
DEPTH/N
The depth value chosen in the requester. This value is only
set if the GADSENABLED switch is used.
TEXT
A text description of the screenmode chosen.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem.
Example
The following puts up a screenmode requester, the result is put in
the SCREENMODEINFO. stem:
REQUEST_SCREENMODE STEM SCREENMODEINFO.
The following puts up a screenmode requester, complete with the
width, height, depth and overscan gadgets. The chosen screenmode
text is put in a message requester:
REQUEST_SCREENMODE GADSENABLED STEM SCREENMODEINFO.
REQUEST_MESSAGE TEXT '"'SCREENMODEINFO.TEXT'"'
Known bugs
1. There are two screenmode requesters that can be used by
ImageStudio. If ImageStudio is running on a Workbench2.1+
Amiga the system ASL screenmode requester is used, if the
Workbench2.04 is running then ImageStudio will use its
internal screenmode requester (Workbench2.04 doesn't have an
ASL screenmode requester). Because of the two different
requesters and the complex way in which the Amiga deals with
screenmodes, the operation of the two can be subtly dif
ferent.
The most noticeable difference is in the handling of the
Amiga's built in screenmodes. A built in screenmode is
something like "LoRes" or "HighRes Interlaced" as opposed to
a disk based screen mode like "MULTISCAN:Productivity" or
"SUPER72:High Res".
If you choose a built in screenmode in the ASL screenmode
requester, the requester will return the screenmode ID
something like "PAL:LoRes". This means that the requester
specifies that the screenmode is "LoRes" and the monitor to
be used is "PAL" (or "NTSC" in America). If you choose a
built in screenmode in the internal screenmode requester, the
requester will return the screenmode ID something like
"LoRes", i.e. *it doesn't specify the monitor to be used*.
This is not usually a problem, but we feel that our
screenmode re quester may be more compatible with older
software which doesn't un derstand the system of specifying
the monitor in the screenmode.
The matter is further complicated if you are using a monitor
with mode promotion. Here, the internal screenmode
requester's screen modes are promoted to the new double
scanning modes (e.g. "HighRes" gets promoted to
"DBLPAL:HighRes"). The ASL screenmodes *aren't* promoted, as
they already contain the desired monitor information in the
screenmode. This feature is either "desirable" or
"undesirable" depending on your point of view. If you've ever
wondered why some screenmodes don't promote, this is why -
they have been told to be specifically "PAL" or "NTSC" in
their screenmode.
If major problems are found in the differences between the
internal and ASL screenmode requesters, we will endevour to
alter the inter nal screenmode requester, but we think this
is unlikely to cause any real problems.
2. To be safe in selecting a mode, you should always click on it
in the requester. When you pass a default screenmode, the
mode highlighted in the requester may not be exactly the same
as the default screen mode given - it may be an equivalent.
Clicking on the screenmode en sures that it returns that
mode's real ID.
REQUEST_STRING
--------------
Command
REQUEST_STRING
Parameters template
TEXT1, TEXT2, TEXT3, STRING, TITLE
Return template
STRING
Description
Opens a string requester, allowing the user to type in one line of
text.
If a filename or directory name is required, it is suggested that
either a special file or directory requester is used instead.
The other ImageStudio windows are automatically blocked when the
requester is opened and unblocked when the requester is closed.
In common with all ImageStudio requesters, if the user presses
`Cancel', an error message is returned. For the script to trap this
error, global error checking must be turned off. See Error
checking, for more information.
Parameters
TEXT1
The top line of description text in the requester. The text
will be left justified.
TEXT2
The middle line of description text in the requester. The
text will be left justified.
TEXT3
The bottom line of description text in the requester. The
text will be left justified.
STRING
The default string to be used in the requester.
TITLE
The text for the title bar of the requester.
Returns
STRING
The string in the requester.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason or the user
cancelled requester, rc2 will contain a string describing the
problem.
Example
The following puts up a string requester, allowing the user to type
in some text. The returned string is put in RESULT:
REQUEST_STRING TEXT2 '"Enter some text"'
The following puts up a string requester with a default string of
"A raytraced image". The description text is displayed over 3
lines:
REQUEST_STRING TEXT1 '"Enter the"' TEXT2 '"desired name"',
TEXT3 '"for the image"' STRING '"A raytraced image"'
Known bugs
None.
RGB_TO_HSV
----------
Command
RGB_TO_HSV
Parameters template
R/N/A, G/N/A, B/N/A
Return template
H/N, S/N, V/N
Description
Converts a RGB colour value into a HSV colour value.
See Colour representations, for more details on RGB and HSV col
our representations.
Parameters
R/N/A
The red value of the colour to convert. Valid values are 0 to
255.
G/N/A
The green value of the colour to convert. Valid values are 0
to 255.
B/N/A
The red of the colour to convert. Valid values are 0 to 255.
Returns
H/N
The hue componant value of the colour.
S/N
The saturation componant value of the colour.
V/N
The value componant of the colour.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following converts yellow from RGB to HSV representation,
putting the result in RESULT:
RGB_TO_HSV 255 255 0
The following converts mid-grey from RGB to HSV representation,
putting the result in the stem COLOUR.:
RGB_TO_HSV 127 127 127 STEM COLOUR.
Known bugs
None.
SAVE
----
Command
SAVE
Parameters template
FILE/A, FORMAT, ARGS, FORCE/S
Return template
None.
Description
Saves the current image out to disk.
See Save, for more details on saving images.
Parameters
FILE/A
The filename of the file to save.
FORMAT
The string containing the format of the file to save. By
default, images are saved out as IFF-ILBM. See File formats,
for more in formation on the available file formats.
ARGS
Any extra arguments that should be passed to the saver.
FORCE/S
By default the user will be warned if they are about to
overwrite a file on the disk. Specifying this switch will
stop such warnings.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following saves the current image out as an IFF-ILBM:
SAVE FILE "ram:Image.ilbm"
The following saves the current image out as an IFF-ILBM, HAM6:
SAVE FILE "ram:Image.ham6" ARGS '"SUBFORMAT HAM6"'
The following saves out the current image as a JPEG, with a quality
setting of 90:
SAVE FILE "ram:Image.jpg" FORMAT "JPEG" ARGS '"QUALITY 90"'
Known bugs
None.
SCALE
-----
Command
SCALE
Parameters template
X/N, Y/N, PERCENT/S, METHOD
Return template
None.
Description
Scales the current image either up or down using different methods
optimised for speed or quality.
The user need not specify both X and Y scales, so scaling an image
to only alter its width or height is possible.
See Scale, for more details on scaling images.
Parameters
X/N
Amount to scale the image in X (width) direction. By default
this value is an absolute value in pixels, but by specifying
the PERCENT option this value can be read as a percentage of
the image's current width.
Y/N
Amount to scale the image in Y (height) direction. By default
this value is an absolute value in pixels, but by specifying
the PERCENT option this value can be read as a percentage of
the image's current height.
PERCENT
Reads the X and Y values as percentages of the image's
current width and height.
METHOD
A string describing the method of scaling to use. By default,
FAST is used but AVERAGE can provide higher quality scales on
24bit images at the cost of computing time.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following scales the image to 800 by 600 pixels:
SCALE 800 600
The following doubles the size of the image:
SCALE 200 200 PERCENT
The following halves the height of the image, using colour average
scaling:
SCALE Y 50 PERCENT METHOD "AVERAGE"
Known bugs
None.
SCREEN_BACK
-----------
Command
SCREEN_BACK
Parameters template
None.
Return template
None.
Description
Moves the ImageStudio screen behind all other open screens.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following moves ImageStudio's screen behind all other open
screens:
SCREEN_BACK
Known bugs
None.
SCREEN_FRONT
------------
Command
SCREEN_FRONT
Parameters template
None.
Return template
None.
Description
Moves the ImageStudio screen in front of all other open screens.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following moves ImageStudio's screen in front of all other open
screens:
SCREEN_FRONT
Known bugs
None.
SELECT_ALL
----------
Command
SELECT_ALL
Parameters template
None.
Return template
None.
Description
Sets the current region to the whole of the image being displayed
in the preview window.
Note that this doesn't always select the whole image; if the user
has zoomed in on a region, only this region will be selected. If
you want to be sure of selecting the whole image, issue a
FULL_IMAGE command first.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following selects the whole of the currently viewed image:
SELECT_ALL
Known bugs
None.
UNDO
----
Command
UNDO
Parameters template
None.
Return template
None.
Description
Un-does the last operation (see ARexx_REDO).
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following un-does the last operation:
UNDO
Known bugs
None.
VIEW
----
Command
VIEW
Parameters template
EXTERNAL/S
Return template
None.
Description
Views the current image using either the internal or external
viewer.
Parameters
EXTERNAL/S
By default the image is shown using the internal viewer,
however by including this parameter the external viewer as
defined in the preferences (see Prefs) will be used.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following views the current image using the internal viewer:
VIEW
The following views the current image using the external viewer:
VIEW EXTERNAL
Known bugs
None.
ZOOM_IN
-------
Command
ZOOM_IN
Parameters template
None.
Return template
None.
Description
Zooms in to the currently selected region in the preview window.
A region has to be selected in order for this command to work.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following zooms in to the currently selected region:
ZOOM_IN
Known bugs
None.
ZOOM_OUT
--------
Command
ZOOM_OUT
Parameters template
None.
Return template
None.
Description
Zooms out by a factor of 3 times in the preview window.
Parameters
None.
Returns
Nothing.
Errors
rc = 0 if the operation was successful.
rc = 10 if the operation failed for any reason, rc2 will contain a
string describing the problem.
Example
The following zooms out by a factor of 3 times in the preview
window:
ZOOM_OUT
Known bugs
None.
Reference
*********
This chapter gives detailed explanations about various aspects of
the program.
File formats
============
Select the file format you wish to investigate.
IFF-ILBM
--------
Name
IFF-ILBM
Load types
Colour mapped, 24 bit, HAM6, HAM8, Extra halfbright.
Compressed and uncompressed.
Save types
Colour mapped, 24 bit, HAM6, HAM8, Extra halfbright.
Compressed and uncompressed.
Description
IFF-ILBM is the Amiga's native bitmap graphic file format.
IFF-ILBM files are usually compressed using simple run-length
compression, but they can be uncompressed for simplicity and speed.
IFF-ILBM is ImageStudio's default save format.
ImageStudio will load and save AGA images on a non-AGA machine.
The original image's screenmode will be preserved, unless changed
by the user (see View_screenmode).
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
SUBFORMAT, DITHER, NOCOMPRESSION/S
SUBFORMAT
By default the image is saved out as the buffer, i.e. either
a 2 to 256 colour colour-mapped image or as 24bit. By
specifying the SUB FORMAT parameter, the user can select
HAM6, HAM8 or EHB as extra save formats. The image will be
converted into the chosen subformat before saving. The image
in ImageStudio remains unchanged.
DITHER
If the SUBFORMAT option is used, DITHER can be set to FS to
give Floyd-Steinberg dithering of the HAM6, HAM8 or EHB image.
NOCOMPRESSION/S
By default the IFF-ILBM image is compressed using simple
run-length compression. Use this switch to save uncompressed
data.
Example
The following saves out the current image in the same format as the
buffer:
SAVE FILE "Image.ilbm"
The following saves out the image as HAM6:
SAVE FILE "Image.ilbm" ARGS '"SUBFORMAT HAM6"'
The following saves out the image as Floyd-Steinberg dithered Extra
halfbright:
SAVE FILE "Image.ilbm" ARGS '"SUBFORMAT EHB DITHER FS"'
BMP
---
Name
BMP
Load types ("Windows" and "OS/2" format).
Colour mapped, 24 bit.
Save types
Colour mapped, 24 bit ("Windows" format).
Description
BMP files are commonly found on PCs running Microsoft Windows.
BMP images are usually uncompressed and come in 2 flavours -
`Windows' and `OS/2'.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
None.
Example
None.
Datatype
--------
Name
Datatype
Load types
Colour mapped.
Save types
None.
Description
The datatype IO module will use any datatypes installed on the
system to try and load the image. The datatype loader will only
work with Workbench3.0 and above.
Datatypes are a poor way of loading images into ImageStudio, for
the following reasons:
1. Datatypes are slow. First the datatype has to convert the
image into its internal format, then ImageStudio has to
convert this to ImageStudio's internal format.
2. Datatypes cannot handle more than 256 colours. Any 24bit
image for mats are converted by the datatype to 256 colours
(or less) which will cause a loss in quality.
3. Datatypes cannot use the progress bar whilst converting the
incomming image. It is therefore not possible to stop a
datatype loading an image during this first phase.
Because of these problems, ImageStudio will only try the datatype
loader as a "last resort" - trying its own loaders before attempt
ing to the use the datatype module.
During testing we have found a few datatypes that cause problems
with odd subformats of certain formats. Obviously, ImageStudio has
no control over the quality of the datatypes installed on the
system.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
None.
Known bugs
The datatype loader currently doesn't handle datatypes which return
HAM (HAM6 or HAM8) images.
Example
None.
EPS
---
Name
EPS
Load types
None.
Save types
Greyscale, 24 bit.
Description
EPS files are ASCII text files written in the PostScript language.
They can be printed out directly to a PostScript printer or
imported into word processing or DTP packages.
EPS files are an ineffecient method of storing files, as they are
uncompressed and are stored as ASCII text as opposed to binary
data. Unless colour is specifically required it is recommended
that EPS files be saved in the greyscale format, as they are one
third of the size of a colour EPS file.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
DPI/N, COLOUR
DPI/N
The resolution of the image in dots per inch. By default, 300
dpi is used.
COLOUR
By default the output image is 256 greyscale. Specifying this
option outputs the image as 24bit colour.
Example
The following saves out a COLOUR EPS file:
SAVE FILE "Image.eps" FORMAT "EPS" ARGS "COLOUR"
The following saves out a 600 by 300 file at 150 dpi, given a print
able size of 4inches by 2inch:
SAVE FILE "Image.eps" FORMAT "EPS" ARGS '"DPI 150"'
GIF
---
Name
GIF
Load types
Colour mapped ("GIF87a" and "GIF89a" formats).
Save types
Colour mapped ("GIF87a" and "GIF89a" formats).
Description
GIF is a common format for images upto 256 colours.
GIF is a trademark of Compuserve Incorporated.
GIF images are normally smaller than their equivalent IFF-ILBM
counterparts due to GIF's LZW compression algorithm. GIF files are
always compressed.
GIF comes in 2 flavours - `GIF87a' and `GIF89a'. GIF87a is the most
popular format; ImageStudio will load in both GIF87a and GIF89a.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
SUBFORMAT,INTERLACED/S,TRANSPARENCY/S,TRANSPCOLOUR/N
SUBFORMAT
By default GIF files are saved as the popular GIF87a format.
By selecting a subformat of GIF89A, the user may include extra
information in the file (e.g. transparent colour information).
Specifying a subformat of GIF89a alone provides no extra
functionality.
INTERLACED/S
By default the information in a GIF file is saved in a
sequential fashion (e.g. line 1,line 2,line 3...). By
specifying this switch the image in saved in a series of
interlaced passes which can give faster redraws on some
viewers (e.g. World Wide Web browsers). Both GIF87A and
GIF89A support interlacing.
Note: This interlace has nothing to do with the Amiga's
interlaced screens.
TRANSPARENCY/S
By specifying this switch, one colour out of the image's
pallete can be made `transparent', causing the background
colour to show through. This again can be useful with World
Wide Web browsers. By default, the transparent colour is
colour 0, but this can be changed (see below). This switch is
only used in the GIF89A subformat.
TRANSPCOLOUR/N
This is the palette entry number that is made transparent if
the TRANSPARENT switch is used. This value is only used in
the GIF89A subformat.
Example
The following saves out a standard GIF87a format file:
SAVE FILE "Image.gif" FORMAT "GIF"
The following saves out a GIF87a file with interlace:
SAVE FILE "Image.gif" FORMAT "GIF" ARGS "INTERLACED"
The following saves out a GIF89a file with a transparent colour of
10:
SAVE FILE "Image.gif" FORMAT "GIF",
ARGS "SUBFORMAT GIF89A TRANSPARENCY TRANSPCOLOUR 10"
IFF-DEEP
--------
Name
IFF-DEEP
Load types
24 bit uncompressed.
Save types
24 bit uncompressed.
Description
The IFF-DEEP format a fast way of storing 24bit data in a IFF
format file.
IFF-DEEP files can be compressed, but ImageStudio currently only
supports the loading and saving of the common uncompressed format.
Saving a colour mapped image as IFF-DEEP will cause the image to be
promoted to 24bits and the colour map information to be lost.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
None.
Example
The following saves out an IFF-DEEP file:
SAVE FILE "Image.deep" FORMAT "IFF-DEEP"
JPEG
----
Name
JPEG
Load types
Greyscale, 24 bit ("JFIF" format).
Save types
Greyscale, 24 bit ("JFIF" format).
Description
JPEG allows the storage of 24-bit images as very small files due to
its lossy compression algorithm. Whereas the compression algorithms
used by other file formats loose none of the image information,
JPEG trades off a little loss in image quality for a high degree of
compression.
As JPEG is a relatively new format, an exact format of the JPEG
file was only agreed on recently. This format is called `JFIF' and
these are the most commonly used JPEG format files - and the
format that ImageStudio loads and saves. It is highly unlikely
that any old JPEG files are still being circulated, but should you
find one it is uncertain whether ImageStudio would accept it.
A high degree of compatibility is obtained with our JPEG loader /
saver routines, as they are based in part on the work of the
Independant JPEG group's routines.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
QUALITY/N, GREYSCALE/S
QUALITY/N
The quality of the jpeg output file. A quality value of 75 is
given by default, resulting in an acceptable degredation of
image quality. For higher degree of compression choose a
lower value(1). For a higher degree of quality, choose a
higher value; values of 85 to 90 result in an almost
unnoticable loss of quality.
GREYSCALE/S
By default the JPEG output is 24bit colour. By using this
option, the image can also be saved in a greyscale format,
where the colour information is lost but the output file size
is correspondingly smaller.
Example
The following saves out the current image as JPEG:
SAVE FILE "Image.jpg" FORMAT "JPEG"
The following saves out the current image as JPEG, with a high
degree of compression:
SAVE FILE "Image.jpg" FORMAT "JPEG" ARGS '"QUALITY 50"'
The following saves out the current image as greyscale JPEG:
SAVE FILE "Image.jpg" FORMAT "JPEG" ARGS '"GREYSCALE"'
---------- Footnotes ----------
(1) Values less than 25 may cause problems with some JPEG readers
PCX
---
Name
PCX
Load types
Colour mapped (2 to 16, 256 colours), 24 bit.
Save types
Colour mapped (256 colours), 24 bit.
Description
PCX files are commonly found on PCs running Microsoft Windows.
PCX files are always compressed using a very inefficient run-length
encoding algorithm. This algorithm can, in some cases, lead to an
increase in file size over an uncompressed image. PCX is included
in ImageStudio for compatibility with other platforms, but we do
not recommend the general storing of images in this format.
ImageStudio only saves 256 colour PCX files as these are the most
compatible accross programs. The specification is a little vague as
to how to handle 2 to 16 colour PCX files.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
None.
Example
None.
PNG
---
Name
PNG
Load types
Colour mapped, 24, 32 and 48bits.
Save types
Colour mapped, 24bit.
Description
PNG is the license free replacement for the GIF file format.
After the controversy with the LZW compression algorithm used in
the GIF file format, it was decided that a new standard should be
created which uses the license free LZ compression algorithm along
with many improvments over the GIF file format (e.g. support for
24bit images). PNG is that format, and supports many advanced
features to obtain the best lossless compression for any type of
bitmap image. PNG also supports features that will find
themselves useful in World Wide Web browsers, etc...
A high degree of compatibility is obtained with our PNG
loader/saver, as it is based in part on the PNGlib code by Group42.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
INTERLACE,TRANSPARENCY/S,TRANSPCOLOUR/N
INTERLACE
By default PNG files are not interlaced, however by
specifying an INTERLACE value of ADAM7 they can be saved out
with 7 levels of in terlacing. This gives progressive redraw
for World Wide Web browsers.
Note: This interlace has nothing to do with the Amiga's
interlaced screens.
TRANSPARENCY/S
By specifying this switch, one colour out of the image's
pallete can be made `transparent', causing the background
colour to show through. This again can be useful with World
Wide Web browsers. By default, the transparent colour is
colour 0, but this can be changed (see below).
TRANSPCOLOUR/N
This is the palette entry number that is made transparent if
the TRANSPARENT switch is used.
Example
The following saves out a standard PNG format file:
SAVE FILE "Image.png" FORMAT "PNG"
The following saves out a PNG file with interlace:
SAVE FILE "Image.png" FORMAT "PNG" ARGS "INTERLACE=ADAM7"
The following saves out a PNG file with a transparent colour of 10:
SAVE FILE "Image.png" FORMAT "PNG",
ARGS "TRANSPARENCY TRANSPCOLOUR 10"
PNM
---
Name
PNM
Load types
Black and white, greyscale, 24bit colour. ASCII and binary.
Save types
Black and white, greyscale, 24bit colour. ASCII and binary.
Description
PNM is an amalgamation of the PBM, PGM and PPM file formats,
commonly found on UNIX machines.
The PNM (Portable aNyMap) family of formats are simple way to store
images as either binary or ASCII format. The formats are
uncompressed, so tend to produce very large files. This module
should handle all PNM formats.
When loading a PNM file, the file *must* have either a `.pnm',
`.pbm', `.pgm' or `.ppm' filename extension.
When saving out a black and white PBM file, the current image is
converted simply into black and white without dithering. If you
require a dithered black and white output you have to reduce the
number of colours first within ImageStudio.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
SUBFORMAT,ASCII/S
SUBFORMAT
SUBFORMAT can be set to either PBM, PGM, PPM depending on
whether the output should be black and white, greyscale or
24bit colour.
ASCII/S
By default PNM files are saved in their more compact binary
format. By specifying this switch, the output can be pure
ASCII text characters. This format produces files whice are
substantially larger than the binary format, but which can be
directly transferred via text only media (e.g. e-mail).
Example
The following saves out a 24bit PNM format file:
SAVE FILE "Image.ppm" FORMAT "PNM" ARGS "SUBFORMAT=PPM"
The following saves a black and white ASCII PBM file:
SAVE FILE "Image.pbm" FORMAT "PNM" ARGS "SUBFORMAT=PBM ASCII"
QRT
---
Name
QRT
Load types
24bit colour.
Save types
24bit colour.
Description
QRT is the output file format for the QuickRayTracer program, as
well as the DKB and POV raytracers.
QRT is a simple uncompressed 24bit colour file format.
When loading a QRT file, the file *must* have either a `.qrt',
`.dkb' or `.pov' filename extension.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
None.
Example
The following saves out a 24bit QTR format file:
SAVE FILE "Image.qrt" FORMAT "QRT"
SGI
---
Name
SGI
Load types
Greyscale and 24bit colour. Compressed and uncompressed.
Save types
Greyscale and 24bit colour. Compressed and uncompressed.
Description
SGI-RGB is the file format used by Silicon Graphics workstations.
SGI-RGB files can be compressed using run length encoding. As the
data is 24bits, this usually has little effect.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
GREYSCALE/S,COMPRESSED/S
GREYSCALE/S
By default the image is saved in full 24bit colour. By
specifying this switch, the output image can be saved as 256
greyscales.
COMPRESSED/S
By specifying this switch the output file may be compressed
using run length encoding.
Example
The following saves out a 24bit SGI format file:
SAVE FILE "Image.sgi" FORMAT "SGI"
The following saves a compressed greyscale image:
SAVE FILE "Image.sgi" FORMAT "SGI" ARGS "GREYSCALE COMPRESSED"
Targa
-----
Name
TARGA
Load types
Colour mapped (2 and 256 colours), 15, 16, 24 and 32bits.
Compressed and uncompressed.
Save types
Colour mapped (256 colours), 24 bit.
Uncompressed.
Description
Targa is usually used for storing 24-bit images, although it can
also handle colour-mapped images as well. The data is usually
stored as simple uncompressed data, however it can also be
run-length encoded to allow compression.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
None.
Example
None.
TIFF
----
Name
TIFF
Load types
Baseline TIFF v6 without CCITT Huffman compression.
Save types
Baseline TIFF v6.
Description
TIFF is a very powerful and flexible file format.
TIFF is probably the most complex and powerful image file format in
common use. TIFF allows the TIFF saver many options in order to
optimize the output file for any given use. This is also the
problem with TIFF; in order for a program to load TIFF images it
must have the ablility to understand all the aspects of the file
format. This leads to great incompatibilties as programs create
TIFF files which cannot be read in by other programs claiming TIFF
loading ability.
In order to overcome this problem, the TIFF Advisory Committee pro
duced a `Baseline' TIFF specification which it was intended that
all TIFF loaders/savers could handle this minimum level of file
format.
The TIFF module provided with ImageStudio is based on this baseline
specification with some differences. The main difference is lack of
compression type 2 (CCITT Huffman) in either the loader or saver.
The loader should handle most other TIFF files and has been tested
with Macintosh and UNIX image processing programs. Images produced
by the module differ from the recommended strip size as dictated by
the TIFF specifications. The TIFF specs recommend that the image is
broken down into strips and saved out as multiple strips;
ImageStudio saves the image out as one large strip to try and
maintain compatibility with programs that cannot handle multiple
strip images.
Due to TIFF's complexity, it is very likely that ImageStudio will
encounter invalid TIFF files that will not load into the program.
Similarly, TIFF files produced by ImageStudio may not load into
other programs (e.g. ones which rely on the strip size being
small). This is a fact of TIFF life, we're afraid. The
ImageStudio TIFF module was written to compatible, not clever.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
COMPRESSION,DPI/N
COMPRESSION
Currently no compression is supported, so COMPRESSION=NONE.
DPI/N
The user may specify the resolution of the output image in
dots-per-inch. Images are saved at a default DPI of 300.
Example
The following saves out a TIFF format file:
SAVE FILE "Image.tiff" FORMAT "TIFF"
The following saves a TIFF image at 72 DPI:
SAVE FILE "Image.tiff" FORMAT "TIFF" ARGS "DPI=72"
VMEM
----
Name
VMEM
Load types
Colour mapped and 24bit.
Save types
Colour mapped and 24bit.
Description
VMEM is the data from ImageStudio's virtual memory swap files, plus
header information.
VMEM files can be loaded and saved by ImageStudio, but their main
use is with the `UnCrash' CLI utility given with ImageStudio for
resurrecting the virtual memory swap files after a crash.
The file format is given below, as this is probably the easiest way
of creating and reading images for ImageStudio for use in other
programs.
File Format
The file format for the VMEM files is given below should you wish
to use the format in your own programs. The file consists of the
of an information header (descriped below) followed by the image
data. The image header is always a fixed size and the image data
is uncom pressed.
Image header:
`C' notation is used, all numbers are stored in Motorola byte
order,
struct {
UBYTE magic1,magic2; // Values 0xDE and 0xAD
UBYTE magic[4]; // Values 'V','M','E','M'
WORD width,height; // Image dimensions
BYTE bytes_per_pixel; // 1 for colour map, 3 for RGB
UBYTE cmap[256][3]; // The colour map (empty for RGB)
};
The structure is not byte padded, i.e. it's 779 bytes in size.
Image data:
The image data is either the colour map values if the image was col
our mapped, or RGB data ordered R,G,B. The length of the image data
should be the width times height times bytes_per_pixel.
ARexx OPEN command ARGS
None.
ARexx SAVE command ARGS
None.
Example
None.
Effects
=======
Select the effect you wish to investigate.
Dynamic range
-------------
Works with
- Full colour-mapped images.
- Full and regions of 24bit images.
Description
Expands the dynamic range of the image to the maximum possible,
without altering the colour balance. This is useful for
automatically increasing the contrast of poor contrast images,
e.g. the output from a scanner.
ARexx EFFECT command ARGS
None.
Flip X
------
Works with
- Full and regions of colour-mapped images.
- Full and regions of 24bit images.
Description
Flips the whole image or selected region horizontally.
ARexx EFFECT command ARGS
None.
Flip Y
------
Works with
- Full and regions of colour-mapped images.
- Full and regions of 24bit images.
Description
Flips the whole image or selected region vertically.
ARexx EFFECT command ARGS
None.
Greyscale
---------
Works with
- Full colour-mapped images.
- Full and regions of 24bit images.
Description
Reduces a colour image to a greyscale image. The actual greyscale
values (or more correctly, luminosity) value is calculated as 30%
of the red component + 59% of the green component + 11% of the blue
component.
ARexx EFFECT command ARGS
None.
Highlight
---------
Works with
- Full colour-mapped images.
- Full and regions of 24bit images.
Description
Turns all colours with greater than the given luminance value to
white.
ARexx EFFECT command ARGS
LUMINANCE/N/A
LUMINANCE/N/A
The luminance value above which pixels should be turned white.
Negative
--------
Works with
- Full colour-mapped images.
- Full and regions of 24bit images.
Description
Negates the colour values of the image.
ARexx EFFECT command ARGS
None.
Random
------
Works with
- Full and regions of 24bit images.
Description
Adds random noise to the image. The greater the random value, the
greater the noise.
ARexx EFFECT command ARGS
RANDOMNESS/N/A
RANDOMNESS/N/A
The amount of randomness to apply to the image. Values range
between 1 and 255.
Remove isolated pixels
----------------------
Works with
- Full and regions of colour-mapped images.
- Full and regions of 24bit images.
Description
Removes any single pixels that are a different colour to their
neighbours. Useful in removing some of the noise in black and white
scans.
ARexx EFFECT command ARGS
None.
Roll X
------
Works with
- Full and regions of colour-mapped images.
- Full and regions of 24bit images.
Description
Rolls the whole image or selected region horizontally, wrapping the
image around.
ARexx EFFECT command ARGS
DISTANCE/N/A
DISTANCE/N/A
The distance, in pixels, to move the image. A positive value
moves the image to the right, a negative value moves the
image to the left.
Roll Y
------
Works with
- Full and regions of colour-mapped images.
- Full and regions of 24bit images.
Description
Rolls the whole image or selected region vertically, wrapping the
image around.
ARexx EFFECT command ARGS
DISTANCE/N/A
DISTANCE/N/A
The distance, in pixels, to move the image. A positive value
moves the image down, a negative value moves the image up.
Pixelise
--------
Works with
- Full and regions of colour-mapped images.
- Full and regions of 24bit images.
Description
Replaces all pixels in the whole image or selected region with
larger pixels.
ARexx EFFECT command ARGS
PIXELSIZE/N/A
PIXELSIZE/N/A
The size, in pixels, of the larger pixel blocks.
Shadow
------
Works with
- Full colour-mapped images.
- Full and regions of 24bit images.
Description
Turns all colours with less than the given luminance value to
black.
ARexx EFFECT command ARGS
LUMINANCE/N/A
LUMINANCE/N/A
The luminance value below which pixels should be turned black.
Image types
===========
ImageStudio works internally with either "colour-mapped" or "24-bit"
images. A description of the workings of both methods follows.
Colour-mapped images
Colour-mapped (palette based) images are used by the standard
(non-HAM) screenmodes on the Amiga. A set of colours (palette) is
chosen for the image and every pixel in the image can have one of
these colours.
Colour-mapped images have the advantage of being a fairly compact
way of storing image information and with a large palette (greater
than 64 colours) high quality images can be produced. They have the
disadvantage that the colours in the image are limited to the col
ours in the palette - with a small palette it becomes a complex
task choosing the correct colours to best portray the image.
24-bit images
24-bit images allow every pixel in the image to be an individual
colour - this is essential for high quality images.
24-bit images have the disadvantage that they are typically at
least 3-times larger than colour-mapped images and require
sophisticated display hardware to show them in their true glory.
When should I use each type of image?
In general, try to leave the image in the format in which it came.
If, for example, you load in a colour-mapped image try and perform
all your operations directly to the colour-mapped image; only
change to a 24-bit image if absolutely necessary (e.g. to apply a
convolution filter).
Colour representations
======================
ImageStudio works internally with the R,G,B format of colour
representation. This is the most common method of storing colour in
formation on computers, as it represents the amounts of intensities
applied to the 3 colour guns of a computer monitor.
H,S,V stands for Hue, Saturation and Value. The hue is the basic
colour (e.g. red, yellow, green, purple etc...), saturation is the
amount of that colour (e.g. weak red, strong red etc...) and the value
is the brightness of the colour.
Tooltypes
=========
ImageStudio supports the configuring of the program via tooltypes
from either the Workbench or CLI.
It is recommended that the user who starts the program from Work
bench uses the "Prefs" requester of ImageStudio to configure it (see
Prefs), whereas the CLI user should be aware of the tooltype options.
Boolean tooltypes can have values `ON' or `YES' for a positive
value, `OFF' or `NO' for a negative values. Numeric tooltypes are
positive and negative integers; floating point values are not allowed.
BALANCE
-------
Name
BALANCE
Type
Boolean
Description
Determines whether the balance floating palette should be open at
startup.
BALANCELEFT
-----------
Name
BALANCELEFT
Type
Numeric
Description
The top position to open the balance floating palette.
BALANCETOP
----------
Name
BALANCETOP
Type
Numeric
Description
The left position to open the balance floating palette.
CONVOLVE
--------
Name
CONVOLVE
Type
Boolean
Description
Determines whether the convolve floating palette should be open at
startup.
CONVOLVELEFT
------------
Name
CONVOLVELEFT
Type
Numeric
Description
The top position to open the convolve floating palette.
CONVOLVETOP
-----------
Name
CONVOLVETOP
Type
Numeric
Description
The left position to open the convolve floating palette.
EFFECT
------
Name
EFFECT
Type
Boolean
Description
Determines whether the effect floating palette should be open at
startup.
EFFECTLEFT
----------
Name
EFFECTLEFT
Type
Numeric
Description
The top position to open the effect floating palette.
EFFECTTOP
---------
Name
EFFECTTOP
Type
Numeric
Description
The left position to open the effect floating palette.
SCRIPTS
-------
Name
SCRIPTS
Type
Boolean
Description
Determines whether the scripts floating palette should be open at
startup.
SCRIPTSLEFT
-----------
Name
SCRIPTSLEFT
Type
Numeric
Description
The top position to open the scripts floating palette.
SCRIPTSTOP
----------
Name
SCRIPTSTOP
Type
Numeric
Description
The left position to open the scripts floating palette.
PREVIEWLEFT
-----------
Name
PREVIEWLEFT
Type
Numeric
Description
The top position to open the preview window.
PREVIEWTOP
----------
Name
PREVIEWTOP
Type
Numeric
Description
The left position to open the preview window.
PREVIEWWIDTH
------------
Name
PREVIEWWIDTH
Type
Numeric
Description
The width to open the preview window.
PREVIEWHEIGHT
-------------
Name
PREVIEWHEIGHT
Type
Numeric
Description
The height to open the preview window.
FONTNAME
--------
Name
FONTNAME
Type
String
Description
The name of the font to use to layout the ImageStudio windows and
menus.
When specifying the font name, the font name must be have a `.font'
appended to its name. For example, to set the default to be
helvetica, the tooltype should be specified as:
FONTNAME=helvetica.font
The fontname is not case sensitive.
FONTSIZE
--------
Name
FONTSIZE
Type
Numeric
Description
The size of the font to use to layout the ImageStudio windows and
menus.
If a large font is specified which would cause some of the windows
to become too large to fit on the ImageStudio screen, the font will
default to topaz 8.
SCREENMODEID
------------
Name
SCREENMODEID
Type
Numeric
Description
The screenmode to open the ImageStudio screen. This value is the
value returned by the REQUEST_SCREENMODE ARexx command in the
MODEID value (see ARexx_REQUEST_SCREENMODE).
SCREENOVERSCAN
--------------
Name
SCREENOVERSCAN
Type
Numeric
Description
The overscan to use with the ImageStudio screen. Valid values are 1
for text overscan, 2 for graphics size, 3 for extreme and 4 for
maximum.
Note, this tooltype has changed from v1.x.x, where it was a string
type.
SCREENDEPTH
-----------
Name
SCREENDEPTH
Type
Numeric
Description
The depth of the ImageStudio screen. Valid values are 1 to 8.
SCREENWIDTH
-----------
Name
SCREENWIDTH
Type
Numeric
Description
The width of the ImageStudio screen. Valid values are greater than
640.
SCREENHEIGHT
------------
Name
SCREENHEIGHT
Type
Numeric
Description
The height of the ImageStudio screen. Valid values are greater than
200.
BLANKSCRIPT
-----------
Name
BLANKSCRIPT
Type
String
Description
The filename of the Blank ARexx script to use a template when a new
script is created in the `Scripts' floating palette.
CONVOLVEDIR
-----------
Name
CONVOLVEDIR
Type
String
Description
The directory to scan on startup for convolution filters to include
in the `Convolves' floating palette.
EXTERNALVIEWER
--------------
Name
EXTERNALVIEWER
Type
String
Description
The external program to run to view the image. The string is in the
format that would be typed from the command line, with a `%s' where
the image filename should be placed.
It is recommended that the string be prefixed with a "run" to allow
the external viewer to run in the background, otherwise ImageStudio
has to wait for the program to finish. For example:
sys:Utilities/VT <NIL: >NIL: %s
would leave ImageStudio waiting until ViewTek had finished, whereas
run sys:Utilities/VT <NIL: >NIL: %s
would run ViewTek in the background. The "<NIL:" and ">NIL:" are
used to stop error messages being printed to the console.
HELPFILE
--------
Name
HELPFILE
Type
String
Description
The full filename of the AmigaGuide help file to provide online
help.
Note, the *full* filename must be provided, a filename taken from
the current directory will not work. For example:
Docs/ImageStudio.guide
will not work, whereas
Work:Graphics/ImageStudio/Docs/ImageStudio.guide
will work fine.
If you do wish to specify the current directory, you may use the
`PROGDIR:' volume assignment. PROGDIR: is set to be the current di
rectory of the current program, each program having its own
PROGDIR: value that can only be used within the program.
Therefore, the above AmigaGuide helpfile can be refered to as:
PROGDIR:Docs/ImageStudio.guide
See Tooltype_HELP, for more information on AmigaGuide help.
IMAGEDIR
--------
Name
IMAGEDIR
Type
String
Description
The default directory to use for images when ImageStudio is loaded.
INTERNALVIEWER
--------------
Name
INTERNALVIEWER
Type
String
Description
The filename of module used for the internal viewer. See See
Internal_viewer, for more information on the different capablities
of the different viewer modules.
KEYFILE
-------
Name
KEYFILE
Type
String
Description
The filename of the keyfile to use to unlock ImageStudio to use
full sized images. Keyfiles are obtaining by registering (see How
to register).
MODULEDIR
---------
Name
MODULEDIR
Type
String
Description
The default directory to use for external modules.
Inside the module directory are other directories containing
modules specific to file loading/saving, viewers, effects etc...
These directories are scanned when ImageStudio starts up.
PALETTEDIR
----------
Name
PALETTEDIR
Type
String
Description
The default directory to use for palettes when ImageStudio is
loaded.
See Palette, for more details on loading palettes into ImageStudio.
PORTNAME
--------
Name
PORTNAME
Type
String
Description
The name of the ARexx portname used by the program.
If a portname by that name already exists, the name is incremented
until a free portname is found. For example, if `IMAGESTUDIO' was
already in use, the following sequence of names would be tried:
`IMAGESTUDIO.1', `IMAGESTUDIO.2', `IMAGESTUDIO.3' ...
When choosing an ARexx portname, try to keep it fairly short.
REXXOUTPUT
----------
Name
REXXOUTPUT
Type
String
Description
The name of the filename to use for ARexx scripts' output. See
Basic ARexx, for more information on this file.
SCREENNAME
----------
Name
SCREENNAME
Type
String
Description
The name of ImageStudio's public screen. This name must be unique,
otherwise the screen won't open.
SCRIPTSDIR
----------
Name
SCRIPTSDIR
Type
String
Description
The default directory that will be scanned for ARexx script files
to put in the `Scripts' floating palette list. Any file with the
chosen ARexx script extension (see Tooltype_SCRIPTSEXT) will be
placed in the list.
SCRIPTSEXT
----------
Name
SCRIPTSEXT
Type
String
Description
The default filename extension for the ImageStudio ARexx scripts.
Only scripts with this extension will be added to the list in the
`Scripts' floating palette.
TEMPDIR
-------
Name
TEMPDIR
Type
String
Description
The directory in which ImageStudio can put its virtual memory tempo
rary swap files. This should be some location on your hard disk, as
the data will be accessed a lot during some operations. If you have
lots of RAM, the temporary directory can be placed in the ram disk
for maximum speed.
TEXTEDITOR
----------
Name
TEXTEDITOR
Type
String
Description
The text editor used to edit ARexx scripts from the `Scripts' float
ing palette. The string is in the format that would be typed from
the command line, with a `%s' where the image filename should be
placed.
It is recommended that the string be prefixed with a "run" to allow
the text editor to run in the background, otherwise ImageStudio has
to wait for the program to finish. For example:
sys:Tools/Memacs <NIL: >NIL: %s
would leave ImageStudio waiting until Microemacs had finished,
whereas
run sys:Tools/Memacs <NIL: >NIL: %s
would run Microemacs in the background. The "<NIL:" and ">NIL:" are
used to stop error messages being printed to the console.
CLIPUNIT
--------
Name
CLIPUNIT
Type
Numeric
Description
The system clipboard used to copy (see Copy) and paste (see Paste)
by the program. There is very little need to change this from the
default value of 0.
PAGESIZE
--------
Name
PAGESIZE
Type
Numeric
Description
The size, in K, of the virtual memory pages. The larger this
number, the more real RAM is used but the less frequent the
accesses to the swap files (see Tooltype_TEMPDIR).
At most, two of these pages will be allocated in RAM at any one
time.
UNDOBUFFERS
-----------
Name
UNDOBUFFERS
Type
Numeric
Description
The number of levels of undo / redo available. The larger this
number, the more disk space is needed for the virtual memory swap
files (this doesn't change the amount of RAM required).
APPICON
-------
Name
APPICON
Type
Boolean
Description
Turns the AppIcon on the Workbench on or off. By having an AppIcon,
users may double-click on the icon to bring the ImageStudio screen
to the front or drop image files on it to load them.
COLOURPREVIEW
-------------
Name
COLOURPREVIEW
Type
Boolean
Description
Switches between a greyscale and colour preview display. A colour
preview can only be displayed when ImageStudio is run on screens
with 16 colours or more. The colour preview will always use an
ordered dither to enhance the display of the image, whereas the
dithering can be turned off when using a greyscale preview (see
Tooltype_COLOURPREVIEW).
The value of the PREVIEWDITHER preference is ignored when using a
colour preview - the colour preview is always dithered.
HELP
----
Name
HELP
Type
Boolean
Description
Turns AmigaGuide help on or off. Turning on AmigaGuide help uses
more RAM as some pages are kept in memory.
MODULECACHE
-----------
Name
MODULECACHE
Type
Boolean
Description
Allows modules to be kept resident in RAM to speed up access times.
Turning this option off forces all modules to be flushed from
memory after they are used; this results in the program requiring
very little memory but involves reading the modules off disk
everytime they are required.
Module caching on will leave the modules resident in RAM, making
for faster access. If the Amiga's operating system starts to get
really low on RAM, the modules are still flushed.
All modules are flushed from memory when the program quits.
PREVIEWDITHER
-------------
Name
PREVIEWDITHER
Type
Boolean
Description
Turns ordered dithering on or off in the preview window. Turning
preview dithering off uses slightly less memory and is slightly
faster than the ordered dither.
PREVIEWREDRAW
-------------
Name
PREVIEWREDRAW
Type
Boolean
Description
Turns the redrawing of the image on or off in the preview window.
Normally this is kept on, but ARexx scripts may wish to turn this
off (see ARexx_PREF_SET) to speed up some processing.
SPLASHWINDOW
------------
Name
SPLASHWINDOW
Type
Boolean
Description
Turns on or off the opening of the `About' window when the program
starts up.
SCREENFRONT
-----------
Name
SCREENFRONT
Type
Boolean
Description
ImageStudio starts up by keeping its screen behind all others. By
turning this tooltype on, the screen is brought to the front after
the startup initialisations have taken place.
Known bugs
==========
Known bugs:
* Using the freely distributable PNG IO module with ImageStudio can
cause side effects with the Scripts/Edit and View/External
options. This is being investigated.
If this causes you problems, remove the PNG IO module from the
ImageStudio modules directory and use the freely distributable PNG
datatype to load PNG files (no save) until we fix the problem.
* Calling AmigaDos commands from an ARexx script running from the
`Scripts' floating palette sometimes causes the machine to freeze
if the command fails and tries to print some text. To fix this,
pipe the input and output of all commands to `NIL:' (see Common
ARexx problems).
* At the moment it is possible to run more than one ARexx script from
outside ImageStudio and this will lead to the ARexx commands from
the multiple scripts being mixed together. We don't know if it's
possible to only run one script at a time externally. If you run
all your scripts from inside ImageStudio, this will never happen.
* Under Workbench2.x the checkbox and mutual exclude (radio button)
gadgets don't scale with font size. This may lead to slightly
strange looking windows with very small or very large fonts.
Workbench3.x scales these gadgets correctly.
* ImageStudio has problems when running with the MagicFileRequester
(MFR) utility. It seems that ImageStudio uses some features of the
ASL file requesters that are unsupported by MFR and this causes MFR
to crash. *This is not our problem, we are not doing anything
wrong*. We've tried to contact the author about this, but to no
avail. We suggest that when using ImageStudio, MFR is not used.
If you think you have found a bug not covered here, please contact
the authors to report it (see The authors).
UnCrash
=======
ImageStudio comes with a small CLI utility called `UnCrash' which
can be useful in trying to recover image data from the virtual memory
swap files left after a crash. It is worth mentioning that there should
be *no way* in which ImageStudio should crash the computer; UnCrash is
for use when ImageStudio is running and an other program causes a crash
or there is a power cut, etc...
UnCrash should be run immediately after the crash; running
ImageStudio again before running UnCrash may cause the original virtual
memory swap files to be overwritten.
UnCrash needs the following information to recover a swap file:
1. The filename of the ImageStudio virtual memory swap file. This will
be located in the directory given by the TEMPDIR preference, and be
called something like `IMAGESTUDIO.1'. Normally these files are
deleted when ImageStudio quits, but if the machine crashes there
is no way these can be automatically deleted.
2. The filename of the output image file to be created. The output
file is in the `VMEM' file format (see VMEM) which only ImageStudio
will load.
3. The width and height of the original image. ImageStudio will only
swap out the raw image data when dealing with virtual memory;
details like the image's number of colours, palette and size are
not saved in the swap file so they must be provided by the user.
UnCrash will always try its best to recover the swap file and create
a useable VMEM image file. Should you specify incorrect dimensions for
the image or the swap file has become damaged in some way, UnCrash may
produce warnings and ImageStudio may warn about the quality of the VMEM
file created by UnCrash.
The following example shows how UnCrash could be used to recover a
640x480 virtual memory swap file after a crash:
UnCrash Work:tmp/IMAGESTUDIO.3 ram:outimage.vmem 640 480
Common questions
****************
If you have any questions about ImageStudio, make sure that it
hasn't already been answered below:
Common question 1
=================
"Why doesn't ImageStudio support TIFF fully?"
The TIFF module supplied with ImageStudio closely follows the
version 6 Baseline TIFF specifications, so it should handle most of the
common TIFF files. We will probably be improving the TIFF module in the
future, but to fully support the TIFF standard would be an enormous
amount of programming.
As a side note, we originally were going to use the TIFFlib from
Silicon Graphics' Sam Leffler. After compiling the code, we had a
library (minus module code) of around 250K. We decided that this was
just too much code to include as a module (of similar size to the
ImageStudio executable itself!), so we wrote our own TIFF code. Bear in
mind that even the TIFFlib doesn't handle all of the TIFF v6
specification, although it does handle most cases.
Common question 2
=================
"Will you be adding SHAM, PCHG ..."
At the moment we have no plans to add SHAM or CTBL formats due to
their hardware dependence. PCHG will probably be added later.
Common question 3
=================
"Can I turn virtual memory off?"
ImageStudio will always work with virtual memory. If you are lucky
enough to have lots of RAM and you wish to use that instead of your
hard disk, simply put the temp. files in the ram disk (see
Tooltype_TEMPDIR). The overhead of using virtual memory from RAM is
negligible.
Common question 4
=================
"What other programs have the authors written?"
Andy and Graham have written "TextureStudio", a shareware Imagine3
format texture renderer. See TextureStudio, for more information.
Andy has written "StickIt" - an Amiga equivalent of the `PostIt'
note; useful for reminding you of things to do.
Graham has written "MultiSample" and "MooseDrive". Multisample is a
utility for converting to and from common Amiga / PC / Atari ST sound
sample formats. MooseDrive is a frantic "viewed from the top" car
racing game with multiple large scrolling tracks and the ability to
upgrade your car as you win races.
All the above programs are available from PD libraries as well as
the Internet's `Aminet' servers.
Common question 5
=================
"How much disk space do the swap files use?"
If the image is colour-mapped, 1 byte per pixel is used. Therefore,
the total number of bytes used is calculated as:
bytes used = image_width x image_height
If the image is 16 million colours, 3 bytes per pixel are used.
Therefore, the total number of bytes used is calculated as:
bytes used = image_width x image_height x 3
Common question 6
=================
"What is the .dvi and .ps documentation?"
".dvi" files are created with TeX program and can be viewed or
printed with appropriate utilities. This allows any user with the TeX
system installed to print the documentation out on any type of printer.
".ps" files are raw PostScript and can be printed on any PostScript
printer simply be sending them directly to the printer.
Common question 7
=================
"Will you be adding support for animations?"
Adding animation support is possible, but very very low on our list
of priorities. If you require image processing of animations with
ImageStudio, we recommend that you obtain a copy of Marcus Moenig's
`MainActor' program. With a bit of ARexx glue, MainActor could split
the animation, pass the frames to ImageStudio for processing and then
join them back into an animation afterwards.
MainActor is a shareware program available from all good PD houses.
Common question 8
=================
"Can you write a general virtual memory program?"
We have been asked many times about writing a general purpose
virtual memory program that can be used with *all* Amigas (i.e.
doesn't require an MMU). To the best of our knowledge, this is not
possible. Our virtual memory routines don't require a MMU because they
are internal to ImageStudio and ImageStudio knows which parts of memory
it is currently using and which are safe to swap out to disk.
A general purpose virtual memory program has to trap processor in
structions and decide whether that particular part of memory needs to
be loaded in. It also has to make smart decisions as to which part of
least used memory can be swapped out. In order to trap these processor
memory accesses, a MMU is vital.
Common question 9
=================
"Why don't you use a MUI for your windows design"
`MUI', or `Magic User Interface', is a tool written by Stefan Stuntz
for designing font sensitive GUIs for Amiga programs.
We do not use MUI for the same reason that we don't use any other
third party GUI software that requires runtime libraries. There are 2
main problems in using third party utilities:
1. The user of ImageStudio is then expected to install extra software
on their system just to get ImageStudio to run. In the case of
MUI's installation, this can be be several hundred kilobytes of
extra files.
2. If at a later date a new version of the Amiga's operating system
causes these third party products to fail, ImageStudio will also
fail. We have been very careful in writing ImageStudio to adhere to
Commodore's programming guidelines and therefore we see no reason
why ImageStudio should fail to work with further operating system
versions. Relying on third party products does not give us that
confidence.
In the very worst case that the author of third party product was
unable or unwilling to update his / her software for the new operat
ing system, ImageStudio would need to be re-written - not something
we have any wish to do.
Common question 10
==================
"Will you be releasing the module format"
When the format of the modules is fixed we will release development
documentation describing how users may write thier own modules.
Currently the module format is liable to change, so it would be unwise
to release such information now.
The authors
***********
ImageStudio is written by Andy Dean and Graham Dean.
Queries should be sent to:
Andy and Graham Dean,
14 Fielding Avenue,
Poynton,
Stockport,
Cheshire.
SK12 1YX
ENGLAND
Andy can be reached for queries (no orders) via Internet Email at:
adean@eleceng.ucl.ac.uk
Note: This Email address may change after September 1995; the postal
address given above will remain valid.
Graham can be reached for queries (no orders) via Internet Email at:
ELA95GND@sheffield.ac.uk
The rate at which ImageStudio progresses depends on a few things:
1. You. If you like and use the program, please register it. If you
like the program but think it is missing something that isn't
already in our future additions list (see Future additions) *let
us know!*.
2. Other work. Graham is studying for a degree and Andy is finishing a
PhD and this work will take priority (sad, but true).
If you find a bug in ImageStudio that is not convered in the `Known
bugs' list (see Known bugs), please inform the authors at the above
addresses; don't assume that someone else will, we don't notice all the
problems ourselves.
Please include as much information about the problem as possible,
including:
* Version of ImageStudio and whether it is the 68000 or 68020
version.
* Amiga model.
* Version of Workbench/Kickstart.
* Amount of RAM (fast and chip), hard disk size and type, processor.
* Any extra hardware boards you have connected to your Amiga.
* Any utilities you are running at the same time as ImageStudio.
* Whether the problem is repeatable or just occasional.
* If you have Enforcer or Mungwall, do these report anything?
We treat all bug reports with the utmost importance but it is
difficult for us to investigate problems with very little detail on how
they happen, so please, send us as much information as possible.
If you are having problems loading a particular file into
ImageStudio, test whether it will load into any another package and if
possible whether other files created by the same program also give
problems. We cannot really test every faulty file, but if files created
by one particular program only give problems on ImageStudio then we'll
look into that.
ImageStudio has been tested on:
- A500, Workbench 2.04, 1Mbyte CHIP RAM, 2Mbyte FAST RAM, A590
85Mbyte SCSI hard drive, Microbotics VXL*30 accelerator (no 32-bit
RAM).
- A1200, Workbench 3.0, 2Mbyte CHIP RAM, 8MByte FAST RAM, Power
ViperI 68030 accelerator card, 68882 FPU, 270Mbyte IDE hard drive.
- A4000/EC030, Workbench 3.0, 2Mbyte CHIP RAM, 8MByte FAST RAM, 68882
FPU, 130Mbyte + 420Mbyte IDE hard drives, CyberVision64 (2MB)
graphics card.
ImageStudio shows no problems with either the Enforcer or Mungwall
debugging tools.
How to register
***************
To receive the full version of ImageStudio, send 15 pounds sterling
(30 US dollars overseas) to:
LH Publishing
13 Gairlock Avenue
Bletchley
MK2 3DH
ENGLAND
larry@em.powernet.co.uk
LH Publishing accept most types of payment, but if you have any
questions please don't hesitate to contact them first.
Note: If you are sending cash, please make sure that it is well
wrapped in the envelope.
In return you will receive the latest version of ImageStudio
complete with printed manual, along with a personal keyfile to unlock
the package. Each keyfile is unique to the registered user, please do
not distribute the keyfile to others as it can be traced back to you.
Allow a resonable time to allow cheque clearance, the processing of the
order, etc...
Upgrades will be offered to registered users free of charge. As we
are now operating a keyfile concept, upgrades can be obtained by
getting the latest version from the Internet, Aminet, BBS's, PD houses
etc... If your local provider doesn't have the latest version, pester
them until they get it!
Upgrades and orders will not now be given by contacting the authors
directly, unless there is a very good reason for it (we're sorry, but
we don't have the resources to deal with all the orders and upgrades
directly!).
The version number of ImageStudio (see About) is to be interpreted
as:
version.revision.subrevision
The `version' shows the main version of the program, `revision' will
be increased as small additions and improvements are made to the
program. The `subrevision' value is incremented with bug fixes. All the
values are simple decimal, not floating point, so version 1.9.0 would
be followed by version 1.10.0.
New versions will be distributed with every change in revision
number, bug fixes are likely to be distributed as "patches" (more
details to follow).
Credits
*******
The authors would like to thank:
* Escom / Amiga Technologies.
* Commodore-Amiga.
* Our beta testers.
* Our parents, for their support (especially our mum for also helping
with the posting and packing!!!).
* Larry Hickmott, for his help and support and the time he's put into
creating the printed manual.
* Matt Dillon, for the `Dice' C compiler.
* SAS Institute, for the `SAS/C' C compiler.
* Ian OConner, for `The Designer' - used to do all the GUI windows de
sign.
* Michael Balzer, for `ARexxBox' - used to implement the ARexx port.
* All those associated with the CyberGraphX retargetable graphics
system.
* Jonathan Forbes, for `LX' - used to decompress the .lha files in
the distribution.
* All the public domain / freeware / shareware authors, for loads of
great software.
* To those on the comp.sys.amiga.programmer newsgroup who've
responded to our programming problems.
* The Independant JPEG Group, for their essential JPEG code and in
formation.
* All those involved with the excellent TeX and `TeXinfo' packages.
Future additions
****************
The following features will probably be added to future versions of
the packages (roughly in order):
* Making the effects external modules.
* Spare buffer.
* Alpha channel buffer.
* Aspect ratio correction in the preview window.
* ARexx macro record.
* Halftoning operators.
* Image rotation.
* Write a separate program used to build ARexx batch processing
scripts by simply clicking on the actions you wish to perform.
* Toolbar.
TextureStudio
*************
Brief description:
TextureStudio supports the loading of texture modules in Imagine3
format. The parameters of the texture can quickly and easily be
adjusted by means of slider gadgets or by typing in the numbers. The
texture can then be mapped onto a plane, cylinder or sphere and
rendered to a preview screen and/or as a 24-bit image to disk.
Many aspects of the texture and render can be altered including axis
position/alignment/size, lighting settings, object colours, object size
etc.
TextureStudio allows the user to quickly render the texture and
explore the effects of changing various parameters without the need to
ray-trace a new image each time something altered.
TextureStudio can render images to disk in IFF-ILBM24, JPEG or Targa
format. This allows high quality images to be rendered and loaded into
other programs. 24-bit images of any size can be rendered, regardless
of memory available.
Some example textures are included in the distribution but Imagine3
is required to be able to use it's textures.
List of feature:
* Supports Imagine3 texture format.
* Control of features via ARexx port.
* Render unlimited number of textures simultaneously.
* Render to HAM screen and 24-bit images on all Amigas.
* Render 24-bit images of any size onto disk in IFF-ILBM24, JPEG or
Targa format, regardless of memory available.
* Saving of HAM preview screen to disk.
* Support for colour, filter and bump type textures.
* Easy adjustment of parameters by means of slider gadgets.
* Map textures onto a plane, cylinder or sphere.
* Control of light colour, distance, position, backlighting and
intensity.
* Adjustment of axis alignment, size and position.
* Control of object size, visible width and image aspect ratio.
* Multiple pass render to allow quick preview of image whilst it
renders.
* 5 levels of anti-aliasing available.
* Preview colours with colourbox window.
* Alter render screens width, height and screenmode.
* Control of all main functions from floating windows.
* Optimised code for 68881 and 68882 FPU's for maximum speed.
* Render plane, cylinder or sphere without any texture to quickly set
up lighting etc.
* Loading and saving of textures settings, parameters and axis
positions.
* Render preferences to alters speed and accuracy of render.
* Configure window positions, screenmode, default settings and then
save preferences to disk.
* Runs on all Amigas with Workbench2.04 or above and an FPU (floating
point unit).
* Standard Workbench2 interface.
* Uses public screen.
Shareware version:
The shareware version is limited in that only the first 8 parameters
of the texture can be adjusted. No other features have been removed.
The full version allows all 16 parameters to be altered.
See How to register, for details on how to register. Registration is
15UK pounds or 30US dollars.